NAV Navbar
PHP Java Visual Basic C# XML Ruby

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)

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.

alt text

Populate the URL field with your USAePay generated WSDL link. Click Go.

alt text

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.

alt text

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.

alt text

Populate the URL field with your USAePay generated WSDL link. Click Go.

alt text

Step 3: Change Service Reference name to "usaepay":

Change the Namespace field to:

usaepay

Then click OK to confirm

alt text

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.

alt text

Populate the URL field with your USAePay generated WSDL link. Click Go.

alt text

A security warning will appear, click Yes and change the Web Reference name to:

usaepay

Then click Add Reference to confirm.

alt text

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

C Sharp Code Examples

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 &amp; 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

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 &amp; 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

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

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 &amp; 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

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

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

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

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

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

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

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

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

Syntax

TransactionResponse postAuth ( ueSecurityToken Token, TransactionRequestObject Params )

Examples

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

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 &amp; 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

Syntax

TransactionResponse runTransaction ( ueSecurityToken Token, TransactionRequestObject Params )

Examples

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 &amp; 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

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
email 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

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

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

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

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

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 &amp; 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

Syntax

TransactionObject getTransaction ( ueSecurityToken Token, string RefNum)

Examples

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 &amp; 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

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 &amp; 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

Syntax

FieldValue getTransactionCustom ( ueSecurityToken Token, string RefNum, string Fields)

Examples

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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:

Related Methods

Syntax

boolean emailTransactionReceiptByName ( ueSecurityToken, TransactionRefNum, integer Start, ReceiptName, EmailAddress)

Examples

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

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
RefNum string Unique transaction reference number assigned by the gateway. You can also use TransKey in the RefNum field.
ReceiptRefNum string Gateway assigned receipt ID
ContentType string Format of receipt (HTML or Text)

Response Parameters

Name Type Description
renderReceiptReturn string Returns base64 encoded receipt

Exceptions

Code Message Advise
20001 Specified transactions was not found Specified RefNum does not match a transaction for this merchant
20030 Requested receipt not found ReceiptRefNum must match an existing receipt
20031 Invalid content type ContentType must be either Text, HTML or Both

Change Log

Version Change
1.7 Changed ReceiptRefNum to type string

renderReceiptByName

Example Request

<?php

    try {
      $ReceiptName = "mycartreceipt";
      $RefNum = 1102910;
      $receipt = $client->renderReceiptByName($token, $RefNum, $ReceiptName, "HTML");
      $receipt = base64_decode($receipt);
    }

    catch(SoapFault $e) {

      echo $e->getMessage();

    }

    ?>

Dim receiptName As String
            receiptName = "test receipt"
            Dim refNum As String
            refNum = "46981789"
            Dim contentType As String
            contentType = "text"
            Dim response As String
            response = client.renderReceiptByName(token, refNum, receiptName, contentType)
            Dim todecode As Byte()
            todecode = Convert.FromBase64String(response)
            MsgBox(System.Text.Encoding.UTF8.GetString(todecode))

string refNum = "46981789";
               string receiptName = "test receipt";
               string ContentType = "text";
               string response;

               try
               {
                   response = client.renderReceiptByName(token, refNum, receiptName, ContentType);
                   byte[] todecode = Convert.FromBase64String(response);
                   MessageBox.Show(string.Concat(System.Text.Encoding.UTF8.GetString(todecode)));

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

<?xml version="1.0" encoding="UTF-8"?>
   <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:ns1="urn:usaepay"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
   <SOAP-ENV:Body>
   <ns1:renderReceiptByName>
   <Token xsi:type="ns1:ueSecurityToken">
   <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
   <PinHash xsi:type="ns1:ueHash">
   <HashValue xsi:type="xsd:string">f5210bf4381989eb937519891cacfa0afecde107</HashValue>
   <Seed xsi:type="xsd:string">11233279528-test</Seed>
   <Type xsi:type="xsd:string">sha1</Type>
   </PinHash>
   <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
   </Token>
   <RefNum xsi:type="xsd:string">102302062</RefNum>
   <ReceiptName xsi:type="xsd:string">tranapi_customer</ReceiptName>
   <ContentType xsi:type="xsd:string">Text</ContentType>
   </ns1:renderReceiptByName>
   </SOAP-ENV:Body>
   </SOAP-ENV:Envelope>

Example Response

xml <?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:renderReceiptByNameResponse>
<renderReceiptByNameReturn xsi:type="xsd:string">WW91ciBjcmVkaXQgY2FyZCBwYXlt ZW50IGhhcyBiZWVuIHJlY2VpdmVkIGJ5IFhNTCBleGFtcGxlIGdlbmVyYXRvci4gQmVsb3cgaXMgD Qp5b3VyIHJlY2VpcHQgb2YgcGF5bWVudC4/DQoNClRyYW5zYWN0aW9uIERldGFpbHMNCi0tLS0tLS 0tLS0tLS0tLS0tLS0tLS0tDQpNZXJjaGFudDogICAgWE1MIGV4YW1wbGUgZ2VuZXJhdG9yDQpUeXB lOiAgICAgICAgQ3JlZGl0IENhcmQgU2FsZQ0KSW52b2ljZSAjOiAgIDEzMzY4MDg4MjMNCkFtb3Vu dDogICAgICAxMzIuODUNCkRlc2NyaXB0aW9uOiBFeGFtcGxlIFRyYW5zYWN0aW9uDQpDYXJkIEhvb GRlcjogVGVzdGVyIEpvbmVzDQpDYXJkIE51bWJlcjogeHh4eHh4eHh4eHh4eHg3Nzc5DQoNCg0KDQ oNCg0KDQp2OC4wMS11ZWdy
</renderReceiptByNameReturn>
</ns1:renderReceiptByNameResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Retrieve a receipt for a transaction

This method allows you to render a receipt template for a given transaction.

RefNum refers to the gateway assigned transaction identifier. ReceiptName refers to the name of the receipt. ContentType refers to the type of receipt requested.

Returns base64 encode receipt. If an error occurs, an exception will be thrown.

Related Methods

Syntax

string renderReceiptByName ( ueSecurityToken, RefNum, ReceiptRefNum, ContentType)

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
RefNum string Unique transaction reference number assigned by the gateway. You can also use TransKey in the RefNum field.
ReceiptRefNum string Gateway assigned receipt ID
ContentType string Format of receipt (HTML or Text)

Response Parameters

Name Type Description
renderReceiptByName string Returns base64 encoded receipt

Exceptions

Code Message Advise
20001 Specified transactions was not found Specified RefNum does not match a transaction for this merchant
20030 Requested receipt not found ReceiptRefNum must match an existing receipt
20031 Invalid content type ContentType must be either Text, HTML or Both

Change Log

Version Change
1.3 Method added in this release

Batch Methods

Close Batch

closeBatch

Example Request

<?php
    try {

    // To close a specific batch use the gateway assigned batchrefnum:

      $batchrefnum='1234567';

   // To close the current batch use '0':
      $batchrefnum='0';
      $res=$tran->closeBatch($sourcekey,$batchrefnum);
    }
    catch (SoapFault $e) {

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

    }
    ?>

try {

    //Creating Close Batch Request object
    CloseBatchRequest Request = new CloseBatchRequest();

    Request.setToken(token);

  //Setting batchRefNum to 0 for current batch, for a different batch set to the Batch Ref Num
    Request.setBatchRefNum(BigInteger.ZERO);

    CloseBatchResponse Result = client.closeBatch(Request);
} catch (Exception e) {
  System.out.println("Soap Exception: " + e.getMessage());
}

Try
                client.closeBatch(token, "0")
                MsgBox("Your batch has closed.")
            Catch ex As Exception
                MsgBox(ex.Message)
            End Try

Boolean result;

    // close current batch
    try
    {
        result = client.closeBatch(token, "0");

        if (result) MessageBox.Show("Batch closed successfully");
        else MessageBox.Show("Batch failed to close");
    }
    catch (Exception err)
    {
        MessageBox.Show(err.Message);
    }

<!--Example Request-->

<?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:closeBatch>
    <Token xsi:type="ns1:ueSecurityToken">
    <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
    <PinHash xsi:type="ns1:ueHash">
    <HashValue xsi:type="xsd:string">3add5373db23ce3407500635de721d83a7c900b9</HashValue>
    <Seed xsi:type="xsd:string">11177496803-test</Seed>
    <Type xsi:type="xsd:string">sha1</Type>
    </PinHash>
    <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
    </Token>
    <BatchRefNum xsi:type="xsd:string">201943</BatchRefNum>
    </ns1:closeBatch>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Example Request

<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:closeBatchResponse>
<closeBatchReturn xsi:type="xsd:boolean">true</closeBatchReturn>
</ns1:closeBatchResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

This method will close or settle an open batch. Upon settlement the funds will be transferred to the merchant's bank account.

To check the status of a batch and determine whether it has already been settled, is still open, or awaiting settlement, use the getBatchStatus method.

Related Methods

Syntax

boolean closeBatch (ueSecurityToken Token, string BatchRefNum)

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
BatchRefNum string A unique batch reference number assigned by the gateway.

Response Parameters

Name Type Description
closeBatchReturn boolean Returns confirmation of the close batch request only if successful. If request fails, an exception will be thrown.

Retrieve Batches

getBatchStatus

Example Request

    <?php
    try {
      $BatchRefNum=0;

      $Result=$client->getBatchStatus($token, $BatchRefNum);  
    }

    catch (SoapFault $e) {

      echo "get Batch Upload status failed :" .$e->getMessage();

    }
    ?>

try {
  //Set BatchNum to the Batch Reference Number of the batch
  //you want to retrieve.  0 is always the current batch
  BigInteger BatchNum = new BigInteger("0");

  BatchStatus batchstat = new BatchStatus();
  batchstat = client.getBatchStatus(token, BigInteger.ZERO);
} catch (Exception e) {
    System.out.println("Soap Exception: " + e.getMessage());
}

Dim BatchRefNum As String
BatchRefNum = "9581"
Dim result as usaepay.BatchStatus = New usaepay.BatchStatus

result = client.getBatchStatus(token, BatchRefNum)
MsgBox(result.Status)

string BatchRefNum;
                BatchRefNum = "9581";

                usaepay.BatchStatus result = new usaepay.BatchStatus();

                try
                {
                    result = client.getBatchStatus(token, BatchRefNum);

                    MessageBox.Show(string.Concat(result.Status));

                }


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

            }

<?xml version="1.0" encoding="UTF-8"?>
   <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:ns1="urn:usaepay"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
   <SOAP-ENV:Body>
   <ns1:getBatchStatus>
   <Token xsi:type="ns1:ueSecurityToken">
   <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
   <PinHash xsi:type="ns1:ueHash">
   <HashValue xsi:type="xsd:string">35aa99bcb731c2eabde8c722dcda648ca49014ed</HashValue>
   <Seed xsi:type="xsd:string">11441581678-test</Seed>
   <Type xsi:type="xsd:string">sha1</Type>
   </PinHash>
   <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
   </Token>
   <BatchRefNum xsi:type="xsd:string">201940</BatchRefNum>
   </ns1:getBatchStatus>
   </SOAP-ENV:Body>
   </SOAP-ENV:Envelope>

Example Response

<?xml version="1.0" encoding="utf-8"?>
   <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:ns1="urn:usaepay"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
   <SOAP-ENV:Body>
   <ns1:getBatchStatusResponse>
   <getBatchStatusReturn xsi:type="ns1:BatchStatus">
   <BatchRefNum xsi:type="xsd:string">201940</BatchRefNum>
   <Closed xsi:type="xsd:string"></Closed>
   <CreditsAmount xsi:type="xsd:double">0</CreditsAmount>
   <CreditsCount xsi:type="xsd:integer">0</CreditsCount>
   <NetAmount xsi:type="xsd:double">1594.2</NetAmount>
   <Opened xsi:type="xsd:string">01/26/2016T15:51:06</Opened>
   <SalesAmount xsi:type="xsd:double">1594.2</SalesAmount>
   <SalesCount xsi:type="xsd:integer">12</SalesCount>
   <Scheduled xsi:type="xsd:string"></Scheduled>
   <Sequence xsi:type="xsd:integer">1</Sequence>
   <Status xsi:type="xsd:string">Open</Status>
   <TransactionCount xsi:type="xsd:integer">12</TransactionCount>
   <VoidsAmount xsi:type="xsd:double">0</VoidsAmount>
   <VoidsCount xsi:type="xsd:integer">0</VoidsCount>
   </getBatchStatusReturn>
   </ns1:getBatchStatusResponse>
   </SOAP-ENV:Body>
   </SOAP-ENV:Envelope>

Retrieves the status of a batch specified by its BatchRefNum.

This method will check on the status of any batch within the merchant console. Enter the BatchRefNum (a unique batch reference number assigned by the gateway) into the search field and the method will return the status of the requested batch.

To pull the status of the currently open batch (which has not yet passed to the gateway), use 0 for the the BatchRefNum.

Related Methods

Syntax

BatchStatus getBatchStatus ( ueSecurityToken Token, string BatchRefNum )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
BatchRefNum string A unique batch reference number assigned by the gateway.

Response Parameters

Name Type Description
%BatchStatus% object Returns confirmation of the close batch request only if successful. If request fails, an exception will be thrown.

Change Log

Version Description
1.7 Changed BatchRefNum to type string

getBatchTransactions

Example Request

    <?php
    try {
      //Set BatchRefNum to the Batch Reference Number of the batch you want
      //to retrieve transactions from.  0 is always the current batch
      $BatchRefNum=0;

      $Result=$client->getBatchTransactions($token, $BatchRefNum);  
    }

    catch (SoapFault $e) {

      die("get Batch Transactions failed :" .$e->getMessage());

    }
    ?>

try {
  //Set BatchNum to the Batch Reference Number of the batch you want
  //to retrieve transactions from.  0 is always the current batch
  BigInteger BatchNum = new BigInteger("0");

  TransactionObjectArray ResultSet = new TransactionObjectArray();
  ResultSet = client.getBatchTransactions(token, BatchNum);
} catch (Exception e) {
    System.out.println("Soap Exception: " + e.getMessage());
}


Dim BatchRefNum As String

' Set BatchRefNum to 0 to get the current batch.  
' Otherwise use batch reference num  (can be found in  Transaction.Details.BatchRefNum)
BatchRefNum = "0"

Dim transactions() As usaepay.TransactionObject = client.getBatchTransactions(token, BatchRefNum)

MsgBox("Found " & transactions.Length & " transactions in current batch")

string BatchRefNum = "9581";

                try
                {
                    usaepay.TransactionObject[] tran = client.getBatchTransactions(token, BatchRefNum);

                    MessageBox.Show(string.Concat("Found ",tran.Length));

                }


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

<?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:getBatchTransactions>
    <Token xsi:type="ns1:ueSecurityToken">
    <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
    <PinHash xsi:type="ns1:ueHash">
    <HashValue xsi:type="xsd:string">58ee8a7a846f692af341e187f06d47ffc75658f3</HashValue>
    <Seed xsi:type="xsd:string">11580947680-test</Seed>
    <Type xsi:type="xsd:string">sha1</Type>
    </PinHash>
    <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
    </Token>
    <BatchRefNum xsi:type="xsd:string">201949</BatchRefNum>
    </ns1:getBatchTransactions>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>e>

Example Response

<?xml version="1.0" encoding="utf-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:getBatchTransactionsResponse>
    <getBatchTransactionsReturn
    SOAP-ENC:arrayType="ns1:TransactionObject[1]
    "xsi:type="ns1:TransactionObjectArray">
    <item xsi:type="ns1:TransactionObject">
    <AccountHolder xsi:type="xsd:string">Tester Jones</AccountHolder>
    <BillingAddress xsi:type="ns1:Address">
    <City xsi:type="xsd:string"></City>
    <Company xsi:type="xsd:string"></Company>
    <Country xsi:type="xsd:string"></Country>
    <Email xsi:type="xsd:string"></Email>
    <Fax xsi:type="xsd:string"></Fax>
    <FirstName xsi:type="xsd:string"></FirstName>
    <LastName xsi:type="xsd:string"></LastName>
    <Phone xsi:type="xsd:string"></Phone>
    <State xsi:type="xsd:string"></State>
    <Street xsi:type="xsd:string"></Street>
    <Street2 xsi:type="xsd:string"></Street2>
    <Zip xsi:type="xsd:string"></Zip>
    </BillingAddress>
    <CheckData xsi:type="ns1:CheckData">
    <Account xsi:nil="true" />
    <Routing xsi:nil="true" />
    </CheckData>
    <CheckTrace xsi:type="ns1:CheckTrace" />
    <ClientIP xsi:type="xsd:string"></ClientIP>
    <CreditCardData xsi:type="ns1:CreditCardData">
    <AvsStreet xsi:type="xsd:string">1234 Main Street</AvsStreet>
    <AvsZip xsi:type="xsd:string">99281</AvsZip>
    <CardCode xsi:type="xsd:string">XXX</CardCode>
    <CardExpiration xsi:type="xsd:string">XXXX</CardExpiration>
    <CardNumber xsi:type="xsd:string">XXXXXXXXXXXX7779</CardNumber>
    <CardPresent xsi:type="xsd:boolean">false</CardPresent>
    <CardType xsi:type="xsd:string">V</CardType>
    <InternalCardAuth xsi:type="xsd:boolean">false</InternalCardAuth>
    <MagStripe xsi:type="xsd:string"></MagStripe>
    <MagSupport xsi:type="xsd:string"></MagSupport>
    <Pares xsi:type="xsd:string"></Pares>
    <TermType xsi:type="xsd:string"></TermType>
    </CreditCardData>
    <CustomerID xsi:type="xsd:string"></CustomerID>
    <CustomFields SOAP-ENC:arrayType="ns1:FieldValue[0]"
    xsi:type="ns1:FieldValueArray" />
    <DateTime xsi:type="xsd:string">2016-01-26 16:51:35</DateTime>
    <Details xsi:type="ns1:TransactionDetail">
    <Amount xsi:type="xsd:double">132.85</Amount>
    <Clerk xsi:type="xsd:string"></Clerk>
    <Currency xsi:type="xsd:string"></Currency>
    <Description xsi:type="xsd:string">Example Transaction</Description>
    <Comments xsi:type="xsd:string"></Comments>
    <Discount xsi:type="xsd:double">0</Discount>
    <Invoice xsi:type="xsd:string">1692861458</Invoice>
    <NonTax xsi:type="xsd:boolean">false</NonTax>
    <OrderID xsi:type="xsd:string"></OrderID>
    <PONum xsi:type="xsd:string"></PONum>
    <Shipping xsi:type="xsd:double">0</Shipping>
    <Subtotal xsi:type="xsd:double">0</Subtotal>
    <Table xsi:type="xsd:string"></Table>
    <Tax xsi:type="xsd:double">0</Tax>
    <Terminal xsi:type="xsd:string"></Terminal>
    <Tip xsi:type="xsd:double">0</Tip>
    </Details>
    <LineItems SOAP-ENC:arrayType="ns1:LineItem[0]"
    xsi:type="ns1:LineItemArray" />
    <Response xsi:type="ns1:TransactionResponse">
    <AcsUrl xsi:nil="true" />
    <AuthAmount xsi:type="xsd:double">132.85</AuthAmount>
    <AuthCode xsi:type="xsd:string">320781</AuthCode>
    <AvsResult xsi:type="xsd:string">Address:Match &amp; 5 Digit Zip: Match
    </AvsResult>
    <AvsResultCode xsi:type="xsd:string">YYY</AvsResultCode>
    <BatchNum xsi:type="xsd:string">1</BatchNum>
    <BatchRefNum xsi:type="xsd:string">201949</BatchRefNum>
    <CardCodeResult xsi:type="xsd:string">Match</CardCodeResult>
    <CardCodeResultCode xsi:type="xsd:string">M</CardCodeResultCode>
    <CardLevelResult xsi:nil="true" />
    <CardLevelResultCode xsi:nil="true" />
    <ConversionRate xsi:type="xsd:double">0</ConversionRate>
    <ConvertedAmount xsi:type="xsd:double">0</ConvertedAmount>
    <ConvertedAmountCurrency xsi:type="xsd:string"></ConvertedAmountCurrency>
    <CustNum xsi:type="xsd:string">0</CustNum>
    <Error xsi:type="xsd:string">Approved</Error>
    <ErrorCode xsi:type="xsd:integer">0</ErrorCode>
    <isDuplicate xsi:type="xsd:boolean">false</isDuplicate>
    <Payload xsi:nil="true" />
    <RefNum xsi:type="xsd:string">103962985</RefNum>
    <Result xsi:type="xsd:string">Approved</Result>
    <ResultCode xsi:type="xsd:string">A</ResultCode>
    <Status xsi:type="xsd:string">Pending</Status>
    <StatusCode xsi:type="xsd:string">P</StatusCode>
    <VpasResultCode xsi:nil="true" />
    </Response>
    <ServerIP xsi:type="xsd:string">209.37.25.121</ServerIP>
    <ShippingAddress xsi:type="ns1:Address">
    <City xsi:type="xsd:string"></City>
    <Company xsi:type="xsd:string"></Company>
    <Country xsi:type="xsd:string"></Country>
    <Email xsi:type="xsd:string"></Email>
    <Fax xsi:type="xsd:string"></Fax>
    <FirstName xsi:type="xsd:string"></FirstName>
    <LastName xsi:type="xsd:string"></LastName>
    <Phone xsi:type="xsd:string"></Phone>
    <State xsi:type="xsd:string"></State>
    <Street xsi:type="xsd:string"></Street>
    <Street2 xsi:type="xsd:string"></Street2>
    <Zip xsi:type="xsd:string"></Zip>
    </ShippingAddress>
    <Source xsi:type="xsd:string">XML Trace Key</Source>
    <Status xsi:type="xsd:string">Authorized (Pending Settlement)</Status>
    <TransactionType xsi:type="xsd:string">Sale</TransactionType>
    <User xsi:type="xsd:string">auto</User>
    </item>
    </getBatchTransactionsReturn>
    </ns1:getBatchTransactionsResponse>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Retrieve transactions in the batch specified by BatchRefNum

This method will return all of the transactions contained within the specified batch. Use this method to retrieve all transaction data including status, type, amount, response and customer information. Please Note: This method can pull a maximum of 1000 transactions at a time. To pull more than 1000 batch transactions, use the searchTransactions method with the BatchID as a filter. Use the limit and start to break the batch into smaller segments so search will not time out..

Related Methods

Syntax

TransactionObject getBatchTransactions ( ueSecurityToken Token, string BatchRefNum )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
BatchRefNum string A unique batch reference number assigned by the gateway.

Response Parameters

Type Description
%TransactionObject% Returns an array of TransactionObjects for all transactions in the specified batch

Change Log

Version Description
1.7 Changed BatchRefNum to type string

searchBatches

Example Request

<?php

try {

// make sure you have prepared data to search on

  $search=array(
    array(
      'Field'=>'closed',
      'Type'=>'gt',
      'Value'=>'2007-04-01'),
    );
  $start=0;
  $limit=100;
  $matchall=true;
  $sort='closed';

  $res=$client->searchBatches($token,$search,$matchall,$start,$limit,$sort);

  print_r($res);
}

catch (SoapFault $e) {

  echo $client->__getLastRequest();
  echo $client->__getLastResponse();
  die("Search batches failed failed :" .$e->getMessage());

}

?>

try {

   SearchParamArray searchParams = new SearchParamArray();
   searchParams.add(new SearchParam("Sequence","eq", "123456"));
   BigInteger start = new BigInteger("0");
   BigInteger limit = new BigInteger("9999999");


   BatchSearchResult BatchResult = new BatchSearchResult();
   BatchResult = client.searchBatches(token, searchParams, true, start, limit, "Sequence");


     System.out.println(BatchResult.getBatchesMatched());
   } catch (Exception e) {
       System.out.println("Soap Exception: " + e.getMessage());
   }

Dim matchAll As Boolean
        matchAll = True
        Dim start As String
        Dim limit As String
        Dim sort As String
        start = "0"
        limit = "10"
        sort = "closed"

        Dim search(0 To 1) As usaepay.SearchParam
        search(0) = New usaepay.SearchParam
        search(0).Field = "closed"
        search(0).Type = "gt"
        search(0).Value = "2010-08-05"

        Dim result As usaepay.BatchSearchResult = New usaepay.BatchSearchResult
        result = client.searchBatches(token, search, matchAll, start, limit, sort)
        MsgBox(result.BatchesMatched)

Boolean matchAll;
            matchAll = true;
            string start = "0";
            string limit = "10";
            string sort = "closed";

            usaepay.SearchParam[] search = new usaepay.SearchParam[2];
            search[0] = new usaepay.SearchParam();

            search[0].Field = "Closed";
            search[0].Type = "gt";
            search[0].Value = "2010-08-05";

            usaepay.BatchSearchResult result = new usaepay.BatchSearchResult();

            try
            {
                result = client.searchBatches(token, search, matchAll, start, limit, sort);

                MessageBox.Show(string.Concat(result.BatchesMatched));

            }


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

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:searchBatches>
<Token xsi:type="ns1:ueSecurityToken">
<ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
<PinHash xsi:type="ns1:ueHash">
<HashValue xsi:type="xsd:string">e64020497009e46cec2da75a7b92d749df748521</HashValue>
<Seed xsi:type="xsd:string">1278362198-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Search SOAP-ENC:arrayType="ns1:SearchParam[1]" xsi:type="ns1:SearchParamArray">
<item xsi:type="ns1:SearchParam">
<Field xsi:type="xsd:string">BatchRefNum</Field>
<Type xsi:type="xsd:string">eq</Type>
<Value xsi:type="xsd:string">198907</Value>
</item>
</Search>
<MatchAll xsi:type="xsd:boolean">true</MatchAll>
<Start xsi:type="xsd:integer">0</Start>
<Limit xsi:type="xsd:integer">100</Limit>
<Sort xsi:type="xsd:string">closed</Sort>
</ns1:searchBatches>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Example Response

<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:searchBatchesResponse>
<searchBatchesReturn xsi:type="ns1:BatchSearchResult">
<Batches SOAP-ENC:arrayType="ns1:BatchStatus[1]" xsi:type="ns1:BatchStatusArray">
<item xsi:type="ns1:BatchStatus">
<BatchRefNum xsi:type="xsd:string">198907</BatchRefNum>
<Closed xsi:type="xsd:string">01/26/2016T11:45:33</Closed>
<CreditsAmount xsi:type="xsd:double">3</CreditsAmount>
<CreditsCount xsi:type="xsd:integer">1</CreditsCount>
<NetAmount xsi:type="xsd:double">4766.17</NetAmount>
<Opened xsi:type="xsd:string">12/02/2015T11:48:43</Opened>
<SalesAmount xsi:type="xsd:double">4769.17</SalesAmount>
<SalesCount xsi:type="xsd:integer">87</SalesCount>
<Scheduled xsi:type="xsd:string"></Scheduled>
<Sequence xsi:type="xsd:integer">2611</Sequence>
<Status xsi:type="xsd:string">Closed</Status>
<TransactionCount xsi:type="xsd:integer">88</TransactionCount>
<VoidsAmount xsi:type="xsd:double">0</VoidsAmount>
<VoidsCount xsi:type="xsd:integer">0</VoidsCount>
</item>
</Batches>
<BatchesMatched xsi:type="xsd:integer">1</BatchesMatched>
<BatchesReturned xsi:type="xsd:integer">1</BatchesReturned>
<Limit xsi:type="xsd:integer">100</Limit>
<StartIndex xsi:type="xsd:integer">0</StartIndex>
</searchBatchesReturn>
</ns1:searchBatchesResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Use this method to search batches that you have already settled. This method allows the following fields to be used in the search: - Sequence - Platform reference number. - Opened - Date batch was opened. - Closed - Date batch was closed.

Use as many or as few search terms as you like. With MatchAll set to "true," all terms must match to return a result. If the search does not yield the desired result, try broadening your search by eliminating terms, or change MatchAll to "false."

Related Methods

Syntax

BatchSearchResult SearchBatches( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string Sort)

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
%SearchParam% array Array of search parameters.
MatchAll boolean If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned.
Start integer Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200)
Limit integer Maximum number of records to return in result set.
Sort string Comma separated list of fields to sort by.

Response Parameters

Type Description
%BatchSearchResult% object

searchBatchesCount

Example Request

<?php

    try {

    // make sure you have prepared data to search on

      $search=array(
        array(
          'Field'=>'closed',
          'Type'=>'gt',
          'Value'=>'2007-04-01'),
        );
      $start=0;
      $limit=100;
      $matchall=true;
      $sort='closed';

      $res=$client->searchBatchesCount($token,$search,$matchall,$start,$limit,$sort);

      print_r($res);
    }

    catch (SoapFault $e) {

      echo $client->__getLastRequest();
      echo $client->__getLastResponse();
      die("Search batches failed failed :" .$e->getMessage());

    }

    ?>

try {

SearchParamArray searchParams = new SearchParamArray();
searchParams.add(new SearchParam("Sequence","eq", "123456"));
BigInteger start = new BigInteger("0");
BigInteger limit = new BigInteger("9999999");


BatchSearchResult BatchResult = new BatchSearchResult();
BatchResult = client.searchBatchesCount(token, searchParams, true, start, limit, "Sequence");


  System.out.println(BatchResult.getBatchesMatched());
} catch (Exception e) {
    System.out.println("Soap Exception: " + e.getMessage());
}

Dim client As usaepay.usaepayService = New usaepay.usaepayService
            Dim token As usaepay.ueSecurityToken

            token = Me.CreateToken("O79erw1433ZBIE0O4Pv25aVDnw3qDVc8", "1234")

            Dim matchAll As Boolean
            matchAll = True
            Dim start As String
            Dim limit As String
            Dim sort As String
            start = "0"
            limit = "10"
            sort = "closed"

            Dim search(0 To 1) As usaepay.SearchParam
            search(0) = New usaepay.SearchParam
            search(0).Field = "closed"
            search(0).Type = "gt"
            search(0).Value = "2010-08-05"

            Dim result As usaepay.BatchSearchResult = New usaepay.BatchSearchResult
            result = client.searchBatchesCount(token, search, matchAll, start, limit, sort)
            MsgBox(result.BatchesMatched)

Boolean matchAll;
               matchAll = true;
               string start = "0";
               string limit = "10";
               string sort = "closed";

               string[] fields = new string[3];
               usaepay.SearchParam[] search = new usaepay.SearchParam[2];
               search[0] = new usaepay.SearchParam();

               search[0].Field = "Closed";
               search[0].Type = "gt";
               search[0].Value = "2010-08-05";

               usaepay.BatchSearchResult result = new usaepay.BatchSearchResult();

               try
               {
                   result = client.searchBatchesCount(token, search, matchAll, start, limit, sort);

                   MessageBox.Show(string.Concat(result.BatchesMatched));

               }


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

<?xml version="1.0" encoding="UTF-8"?>
   <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:ns1="urn:usaepay"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
   <SOAP-ENV:Body>
   <ns1:searchBatchesCount>
   <Token xsi:type="ns1:ueSecurityToken">
   <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
   <PinHash xsi:type="ns1:ueHash">
   <HashValue xsi:type="xsd:string">b9f7bc3619181e72c13560322851d7994f638fe5</HashValue>
   <Seed xsi:type="xsd:string">12002583462-test</Seed>
   <Type xsi:type="xsd:string">sha1</Type>
   </PinHash>
   <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
   </Token>
   <Search SOAP-ENC:arrayType="ns1:SearchParam[1]" xsi:type="ns1:SearchParamArray">
   <item xsi:type="ns1:SearchParam">
   <Field xsi:type="xsd:string">Sequence</Field>
   <Type xsi:type="xsd:string">eq</Type>
   <Value xsi:type="xsd:string">2611</Value>
   </item>
   </Search>
   <MatchAll xsi:type="xsd:boolean">true</MatchAll>
   <Start xsi:type="xsd:integer">0</Start>
   <Limit xsi:type="xsd:integer">100</Limit>
   <Sort xsi:type="xsd:string">sequence</Sort>
   </ns1:searchBatchesCount>
   </SOAP-ENV:Body>
   </SOAP-ENV:Envelope>

Example Response

<?xml version="1.0" encoding="utf-8"?>
   <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:ns1="urn:usaepay"
   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
   <SOAP-ENV:Body>
   <ns1:searchBatchesCountResponse>
   <searchBatchesCountReturn xsi:type="ns1:BatchSearchResult">
   <Batches SOAP-ENC:arrayType="ns1:BatchStatus[0]" xsi:type="ns1:BatchStatusArray" />
   <BatchesMatched xsi:type="xsd:integer">1</BatchesMatched>
   <BatchesReturned xsi:type="xsd:integer">1</BatchesReturned>
   <Limit xsi:type="xsd:integer">100</Limit>
   <StartIndex xsi:type="xsd:integer">0</StartIndex>
   </searchBatchesCountReturn>
   </ns1:searchBatchesCountResponse>
   </SOAP-ENV:Body>
   </SOAP-ENV:Envelope>

Search previously settled batches, return only counts Identical to the searchBatches method except only the batch counts are returned. Like searchBatches, this method returns BatchSearchResult. The only difference is that BatchSearchResult.Batches is left empty. This method provides a quicker way to determine the size of the result set before starting to retrieve the full search results.

Related Methods

Syntax

BatchSearchResult( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string Sort)

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
%SearchParam% array Array of search parameters.
MatchAll boolean If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned.
Start integer Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200)
Limit integer Maximum number of records to return in result set.
Sort string Comma separated list of fields to sort by.

Response Parameters

Name Type Description
%BatchSearchResult% object Returns the result of the batch search based on the search parameters set.

Customer Methods

Customers

addCustomer

Example Request

    <?php
    try {

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

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

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

    }

    catch(SoapFault $e) {

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

    try {

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

         CustomerObject customer = new CustomerObject();

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

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

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

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


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


    // Create request object

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

    // Create response object
         BigInteger response;


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

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

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

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

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

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

            customer.PaymentMethods = payMethod
            Dim response As String

            response = client.addCustomer(token, customer)
            MsgBox(String.Concat(response))

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

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

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

                customer.PaymentMethods = payMethod;
                string response;

                try
                {
                    response = client.addCustomer(token, customer);
                    MessageBox.Show(string.Concat(response));
                }

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

    <?xml version="1.0" encoding="UTF-8"?>
       <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
       xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
       SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
          <SOAP-ENV:Body>
             <ns1:addCustomer>
                <Token xsi:type="ns1:ueSecurityToken">
                   <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
                   <PinHash xsi:type="ns1:ueHash">
                      <HashValue xsi:type="xsd:string">dcdce3cd41a4fe05b3026cb494b82c01487266fe</HashValue>
                      <Seed xsi:type="xsd:string">11638841859-test</Seed>
                      <Type xsi:type="xsd:string">sha1</Type>
                   </PinHash>
                   <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
                </Token>
                <CustomerData xsi:type="ns1:CustomerObject">
                   <Amount xsi:type="xsd:double">44.93</Amount>
                   <BillingAddress xsi:type="ns1:Address">
                      <City xsi:type="xsd:string">Los Angeles</City>
                      <Company xsi:type="xsd:string">Acme Corp</Company>
                      <Country xsi:type="xsd:string">US</Country>
                      <Email xsi:type="xsd:string">joe@example.com</Email>
                      <Fax xsi:type="xsd:string">333-333-3334</Fax>
                      <FirstName xsi:type="xsd:string">Clariss</FirstName>
                      <LastName xsi:type="xsd:string">Doe</LastName>
                      <Phone xsi:type="xsd:string">333-333-3333</Phone>
                      <State xsi:type="xsd:string">CA</State>
                      <Street xsi:type="xsd:string">1234 main st</Street>
                      <Street2 xsi:type="xsd:string">Suite #123</Street2>
                      <Zip xsi:type="xsd:string">12345</Zip>
                   </BillingAddress>

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

Example Response

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

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

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

Related Methods

Syntax

string addCustomer ( ueSecurityToken Token, CustomerObject CustomerData )

Examples

Request Parameters

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

Response Parameters

Name Type Description
addCustomerReturn string Returns result of add customer request

Change Log

Version Change
1.7 Changed ReturnValue to type string

enableCustomer

Example Request

    <?php
try {
     $custnum="12345678";

     $res=$client->enableCustomer($token, $custnum);     

     }

 catch(SoapFault $e) {

     echo "soap fault: " .$e->getMessage();

     }
        ?>

try {
        //Set CustNum for the Customer that you want to enable
        BigInteger CustNum = new BigInteger("12345678");

        client.enableCustomer(token, CustNum);
    } catch (Exception e) {
            System.out.println("Soap Exception: " + e.getMessage());
    }

Dim custNum As String
                 custNum = "103125"

                 Dim response As Boolean
                 response = client.enableCustomer(token, custNum)
                 MsgBox(response)

string custNum = "89147";

                             Boolean response;

                             try
                             {
                                     response = client.enableCustomer(token, custNum);
                                     if (response)
                                     {
                                             MessageBox.Show(string.Concat("Succesfull"));
                                     }
                                     else MessageBox.Show(string.Concat("Error!"));
                             }

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

<?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:enableCustomer>
    <Token xsi:type="ns1:ueSecurityToken">
    <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
    <PinHash xsi:type="ns1:ueHash">
    <HashValue xsi:type="xsd:string">850e5f0b4fcc4fe4dc6a4db54ddeb7b78bb2c951</HashValue>
    <Seed xsi:type="xsd:string">1396230635-test</Seed>
    <Type xsi:type="xsd:string">sha1</Type>
    </PinHash>
    <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
    </Token>
    <CustNum xsi:type="xsd:string">4603318</CustNum>
    </ns1:enableCustomer>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Example Response

<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:enableCustomerResponse>
<enableCustomerReturn xsi:type="xsd:boolean">true</enableCustomerReturn>
</ns1:enableCustomerResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Enable recurring billing for a customer specified by CustNum.

This method allows you to begin a recurring billing cycle for an individual customer using their CustNum (unique customer number assigned by the gateway) as a reference. If you have lost or cannot remember the customer's CustNum, use the searchCustomerID method to retrieve it.

The recurring billing cycle can begin on any date you choose and can be set to any of the following cycles: Daily, Weekly, Bi-Weekly (every 2 weeks), Monthly, Bi-Monthly (every 2 months), Quarterly, Bi-Annually (every 6 months), and Annually.

You can also set the start and end dates, amount to be charged, and the total number of transactions for the recurring billing cycle.

Once a customer has been added to a recurring billing cycle, you can monitor and change the recurring billing settings from within the merchant console.

You can disable a customer's recurring billing cycle at any time using the disableCustomer method.

For more information about recurring billing, please refer to the support documentation in the merchant console.

Related Methods

Syntax

boolean enableCustomer ( ueSecurityToken Token, string CustNum )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
CustNum string A unique customer number assigned by the gateway

Response Parameters

Name Type Description
enableCustomerReturn boolean Returns result of recurring billing request. Possible values are: Approved, Error, or Declined.

Change Log

Version Change
1.7 Changed CustNum to type string

disableCustomer

Example Request

    <?php
    try {

      $custnum='56805';

      print_r($client->disableCustomer($token,$custnum));

      }

    catch(SoapFault $e) {

      echo $e->getMessage();
      }
        ?>

try {
      //Set CustNum for the Customer that you want to disable
      BigInteger CustNum = new BigInteger("12345678");

      client.disableCustomer(token, CustNum);
    } catch (Exception e) {
        System.out.println("Soap Exception: " + e.getMessage());
    }

Dim custNum As String
             custNum = "103125"

             Dim response As Boolean
             response = client.disableCustomer(token, custNum)
             MsgBox(response)


string custNum = "89147";

                        Boolean response;

                        try
                        {
                                response = client.deleteCustomer(token, custNum);
                                if (response)
                                {
                                        MessageBox.Show(string.Concat("Succesfull"));
                                }

                        }

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

<?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:disableCustomer>
    <Token xsi:type="ns1:ueSecurityToken">
    <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
    <PinHash xsi:type="ns1:ueHash">
    <HashValue xsi:type="xsd:string">029f32e4a817c9a0f307fa3a50ef126d79177409</HashValue>
    <Seed xsi:type="xsd:string">11652288220-test</Seed>
    <Type xsi:type="xsd:string">sha1</Type>
    </PinHash>
    <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
    </Token>
    <CustNum xsi:type="xsd:string">4603339</CustNum>
    </ns1:disableCustomer>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Example Response

<?xml version="1.0" encoding="utf-8"?>
     <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
     xmlns:ns1="urn:usaepay"
     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
     SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
     <SOAP-ENV:Body>
     <ns1:disableCustomerResponse>
     <disableCustomerReturn xsi:type="xsd:boolean">true</disableCustomerReturn>
     </ns1:disableCustomerResponse>
     </SOAP-ENV:Body>
     </SOAP-ENV:Envelope>

Disable the recurring billing for a customer specified by CustNum.

This method allows you to stop a customer's recurring billing cycle using the CustNum (unique customer number assigned by the gateway) as a reference. If you have lost or cannot remember the customer's CustNum, use the searchCustomerID method to retrieve it.

You can resume a customer's recurring billing cycle at any time using the enableCustomer method.

Related Methods

Syntax

boolean disableCustomer ( ueSecurityToken Token, string CustNum )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
CustNum string A unique customer number assigned by the gateway

Response Parameters

Name Type Description
disableCustomerReturn boolean Returns confirmation of the disable recurring billing request only if request is successful. If request fails, an exception will be thrown

Change Log

Version Change
1.7 Changed CustNum to type string

deleteCustomer

Example Request

    <?php
try {

  $custnum=$this->createCustomer();

  $res=$client->deleteCustomer($token, $custnum);

  $this->assertTrue($res);

}

catch(SoapFault $e) {

  die("soap fault: " .$e->getMessage());

}

?>

try {
         //Set CustNum for Customer you want to delete
         BigInteger CustNum = BigInteger("12345678");

         //Delete Customer
         client.deleteCustomer(token, CustNum);
     } catch (Exception e) {
             System.out.println("Soap Exception: " + e.getMessage());
     }

Dim custNum As String
            custNum = "103125"

            Dim response As Boolean
            response = client.deleteCustomer(token, custNum)
            MsgBox(response)

string custNum = "89792";

                        Boolean response;

                        try
                        {
                                response = client.deleteCustomer(token, custNum);
                                if (response)
                                {
                                        MessageBox.Show(string.Concat("Succesfull"));
                                }
                                else MessageBox.Show(string.Concat("Error!"));
                        }

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

<?xml version="1.0" encoding="UTF-8"?>
     <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
     xmlns:ns1="urn:usaepay"
     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
     SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
     <SOAP-ENV:Body>
     <ns1:deleteCustomer>
     <Token xsi:type="ns1:ueSecurityToken">
     <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
     <PinHash xsi:type="ns1:ueHash">
     <HashValue xsi:type="xsd:string">18abc8b8381259e9aea49d5e89a39521ff8a2666</HashValue>
     <Seed xsi:type="xsd:string">12130139400-test</Seed>
     <Type xsi:type="xsd:string">sha1</Type>
     </PinHash>
     <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
     </Token>
     <CustNum xsi:type="xsd:string">4600537</CustNum>
     </ns1:deleteCustomer>
     </SOAP-ENV:Body>
     </SOAP-ENV:Envelope>

Example Response

<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:deleteCustomerResponse>
<deleteCustomerReturn xsi:type="xsd:boolean">true</deleteCustomerReturn>
</ns1:deleteCustomerResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Delete the customer specified by CustNum.

This method requires the use of the CustNum, a unique customer number assigned by the gateway. If you have lost or cannot remember the customer's CustNum, use the searchCustomers method to find the correct CustNum.

Related Methods

Syntax

boolean deleteCustomer ( ueSecurityToken Token, string CustNum )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
CustNum string A unique customer number assigned by the gateway

Response Parameters

Name Type Description
deleteCustomerReturn boolean Returns confirmation of request only if successful. If request fails, an exception will be thrown.

getCustomer

Example Request

<?php
try {

      $custnum='532';
      print_r($client->getCustomer($token,$custnum));

    }

    catch(SoapFault $e) {

      echo $e->getMessage();
      echo "\n\nRequest: " . $client->__getLastRequest();
      echo "\n\nResponse: " . $client->__getLastResponse();

    }
    ?>

try {
         //Set custnum to the Customer Number of customer you want to retrieve.
         BigInteger custnum = new BigInteger("12345678");

         CustomerObject customer = new CustomerObject();

         customer = client.getCustomer(token, custnum);
     } catch (Exception e) {
             System.out.println("Soap Exception: " + e.getMessage());
     }

Dim custNum As String
            custNum = "103125"

            Dim customer As usaepay.CustomerObject
            customer = New usaepay.CustomerObject()

            customer = client.getCustomer(token, custNum)

            MsgBox(customer.CustomerID)

string custNum = "89147";

                string response;
                usaepay.CustomerObject customer = new usaepay.CustomerObject();

                try
                {
                    customer = client.getCustomer(token, custNum);

                    MessageBox.Show(string.Concat("CustNum: ", customer.CustomerID));


                }

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

<?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:getCustomer>
    <Token xsi:type="ns1:ueSecurityToken">
    <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
    <PinHash xsi:type="ns1:ueHash">
    <HashValue xsi:type="xsd:string">0a8ac70263392c59f63476aa13a97cc7e8672a5d</HashValue>
    <Seed xsi:type="xsd:string">1176474488-test</Seed>
    <Type xsi:type="xsd:string">sha1</Type>
    </PinHash>
    <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
    </Token>
    <CustNum xsi:type="xsd:string">4606615</CustNum>
    </ns1:getCustomer>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Example Response

<?xml version="1.0" encoding="utf-8"?>
     <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
     xmlns:ns1="urn:usaepay"
     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
     <SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
     <SOAP-ENV:Body>
     <ns1:getCustomerResponse>
     <getCustomerReturn xsi:type="ns1:CustomerObject">
     <Amount xsi:type="xsd:double">44.93</Amount>
     <BillingAddress xsi:type="ns1:Address">
     <City xsi:type="xsd:string">Los Angeles</City>
     <Company xsi:type="xsd:string">Acme Corp</Company>
     <Country xsi:type="xsd:string">US</Country>
     <Email xsi:type="xsd:string">joe@example.com</Email>
     <Fax xsi:type="xsd:string">333-333-3334</Fax>
     <FirstName xsi:type="xsd:string">John</FirstName>
     <LastName xsi:type="xsd:string">Doe</LastName>
     <Phone xsi:type="xsd:string">333-333-3333</Phone>
     <State xsi:type="xsd:string">CA</State>
     <Street xsi:type="xsd:string">1234 main st</Street>
     <Street2 xsi:type="xsd:string">Suite #123</Street2>
     <Zip xsi:type="xsd:string">12345</Zip>
     </BillingAddress>
     <Created xsi:type="xsd:dateTime">2015-12-07T15:45:32+08:00</Created>
     <Currency xsi:type="xsd:string">0</Currency>
     <CustNum xsi:type="xsd:string">4606615</CustNum>
     <CustomData xsi:type="xsd:string"></CustomData>
     <CustomFields SOAP-ENC:arrayType="ns1:FieldValue[0]"
     xsi:type="ns1:FieldValueArray" />
     <CustomerID xsi:type="xsd:string">711099247</CustomerID>
     <Description xsi:type="xsd:string">Weekly Bill</Description>
     <Enabled xsi:type="xsd:boolean">true</Enabled>
     <Failures xsi:type="xsd:int">0</Failures>
     <LookupCode xsi:type="xsd:string"></LookupCode>
     <Modified xsi:type="xsd:dateTime">2015-12-07T15:45:32+08:00</Modified>
     <Next xsi:type="xsd:string">2016-12-01T12:00:00</Next>
     <Notes xsi:type="xsd:string">Testing the soap addCustomer Function</Notes>
     <NumLeft xsi:type="xsd:integer">50</NumLeft>
     <OrderID xsi:type="xsd:string">2073065117</OrderID>
     <PaymentMethods SOAP-ENC:arrayType="ns1:PaymentMethod[1]"
     xsi:type="ns1:PaymentMethodArray">
     <item xsi:type="ns1:PaymentMethod">
     <MethodType xsi:type="xsd:string">cc</MethodType>
     <MethodID xsi:type="xsd:string">112</MethodID>
     <MethodName xsi:type="xsd:string">CreditCard</MethodName>
     <SecondarySort xsi:type="xsd:integer">8</SecondarySort>
     <Created xsi:type="xsd:dateTime">2015-12-07T15:45:32+08:00</Created>
     <Modified xsi:type="xsd:dateTime">2015-12-07T15:45:32+08:00</Modified>
     <CardExpiration xsi:type="xsd:string">2018-12</CardExpiration>
     <CardNumber xsi:type="xsd:string">XXXXXXXXXXXX7779</CardNumber>
     <CardType xsi:type="xsd:string">V</CardType>
     </item>
     </PaymentMethods>
     <PriceTier xsi:type="xsd:string"></PriceTier>
     <ReceiptNote xsi:type="xsd:string">addCustomertestCreatedCharge</ReceiptNote>
     <Schedule xsi:type="xsd:string">Weekly</Schedule>
     <SendReceipt xsi:type="xsd:boolean">true</SendReceipt>
     <Source xsi:type="xsd:string">Recurring</Source>
     <Tax xsi:type="xsd:double">0</Tax>
     <TaxClass xsi:type="xsd:string"></TaxClass>
     <User xsi:type="xsd:string">(Auto)</User>
     <URL xsi:type="xsd:string"></URL>
     </getCustomerReturn>
     </ns1:getCustomerResponse>
     </SOAP-ENV:Body>
     </SOAP-ENV:Envelope>

Retrieve the customer details for a given CustNum.

This method requires the use of the CustNum, a unique customer number assigned by the gateway. If you have lost or cannot remember the customer's CustNum, use the searchCustomers method to find the correct CustNum.

Customer details include CustNum (the gateway assigned customer number), CustID (merchant assigned customer ID), billing address, receipt settings, recurring billing settings, and other pertinent information.

Related Methods

Syntax

boolean getCustomer ( ueSecurityToken Token, string CustNum )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
CustNum string A unique customer number assigned by the gateway

Response Parameters

Name Type Description
%CustomerObject% object Returns customer information such as customer number, merchant assigned customer ID, billing address, receipt settings, recurring billing settings, and other pertinent information. Customers will only show up to 1000 payment methods per customer.

Change Log

Version Change
1.7 Changed CustNum to type string

updateCustomer

Example Request

<?php

    try {

      $customer=$tran->getCustomer($token, 1309);

      $customer->Amount=29.99;
      $customer->Description='New Description';

      $res=$client->updateCustomer($token, 1309, $customer);

      print_r($res);

    }

    catch(SoapFault $e) {

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

    }

    ?>

Dim CustNum As String
            CustNum = "103125"

            Dim customer As usaepay.CustomerObject = New usaepay.CustomerObject
            customer = client.getCustomer(token, CustNum)
            customer.Amount = 29.99

            Dim response As Boolean

            response = client.updateCustomer(token, CustNum, customer)
            MsgBox(response)

string CustNum = "89147";

usaepay.CustomerObject customer = new usaepay.CustomerObject();
customer = client.getCustomer(token, CustNum);
customer.Amount = 29.99;

Boolean response;

try
{
        response = client.updateCustomer(token, CustNum, customer);
        MessageBox.Show(string.Concat(response));
}
catch (Exception err)
{
        MessageBox.Show(err.Message);
}

Replace all data for customer specified by CustNum.

This method completely replaces all existing customer data for a specific customer. If you leave any of the fields blank or do not include them in the request, it will delete those fields on the customer record.

This method requires the use of the CustNum, a unique customer number assigned by the gateway. If you have lost or cannot remember the customer's CustNum, use the searchCustomers method to find the correct CustNum.

Depending on your programming language, you should be able to retrieve the customer object using the getCustomer method, alter any fields you want and then submit it back using the updateCustomer method.

To update only a few specific fields, use the quickUpdateCustomer method.

Related Methods

Syntax

boolean updateCustomer ( ueSecurityToken Token, string CustNum, CustomerObject CustomerData)

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
CustNum string A unique customer number assigned by the gateway
%CustomerObject% CustomerData Includes customer information such as customer number, merchant assigned customer ID, billing address, receipt settings, recurring billing settings, and other pertinent information

Response Parameters

Name Type Description
updateCustomerReturn boolean Returns confirmation of customer update only if data revision was successful. If update fails, an exception will be thrown

Change Log

Version Change
1.7 Changed CustNum to type string

quickUpdateCustomer

Example Request

<?php

try {

    $custnum='532';
    $update=array(
        array('Field'=>'CardExp'   , 'Value'=>'0913'),
        array('Field'=>'CardNumber', 'Value'=>'4444555566667779'),
        array('Field'=>'Amount'    , 'Value'=>'1.34'),
        array('Field'=>'Address'   , 'Value'=>'Time: ' . mktime()),
        array('Field'=>'CustomData', 'Value'=> serialize(array("MyField" => "myval"))),      
        );

    print_r($client->quickUpdateCustomer($token,$custnum, $update));

}

catch(SoapFault $e) {

    echo "Error: " . $e->faultstring;
    echo "\n\nRequest: " . $client->__getLastRequest();
    echo "\n\nResponse: " . $client->__getLastResponse();

}

catch(Exception $e) {
    echo 'Error: ' . $e->getMessage();

}

?>  

try {

        BigInteger custnum = new BigInteger("1235");

        // Create array of fields to update
        FieldValueArray updateData = new FieldValueArray();
        updateData.add(new FieldValue("Schedule", "daily"));
        updateData.add(new FieldValue("Amount", "5.00"));

        // run quick update
        boolean response = client.quickUpdateCustomer(token, custnum, updateData);

} catch (Exception e) {
        System.out.println("Soap Exception: " + e.getMessage());
}

Dim custNum As String
                     custNum = "103125"

                     Dim fields(0 To 1) As usaepay.FieldValue


                     For i As Integer = 0 To 1
                             fields(i) = New usaepay.FieldValue
                     Next i

                     fields(0).Field = "Schedule"
                     fields(0).Value = "monthly"
                     fields(1).Field = "Amount"
                     fields(1).Value = "5.00"

                     Dim response As Boolean

                     response = client.quickUpdateCustomer(token, custNum, fields)
                     MsgBox(response)

string custNum = "89147";

usaepay.FieldValue[] fields = new usaepay.FieldValue[2];

for (int i = 0; i < 2; i++) {
        fields[i] = new usaepay.FieldValue();
}

fields[0].Field = "Schedule";   fields[0].Value = "monthly";
fields[1].Field = "Amount";     fields[1].Value = "5.00";

Boolean response;

try
{
        response = client.quickUpdateCustomer(token, custNum, fields);
        MessageBox.Show(string.Concat(response));
}

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

<?xml version="1.0" encoding="UTF-8"?>
            <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ns1="urn:usaepay"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
             SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
                 <SOAP-ENV:Body>
                        <ns1:quickUpdateCustomer>
                             <Token xsi:type="ns1:ueSecurityToken">
                                    <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
                                    <PinHash xsi:type="ns1:ueHash">
                                         <HashValue xsi:type="xsd:string">aad4e875fdc4ff508e7b426e0bd5f2f322946b75</HashValue>
                                         <Seed xsi:type="xsd:string">1425719194-test</Seed>
                                         <Type xsi:type="xsd:string">sha1</Type>
                                    </PinHash>
                                    <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
                             </Token>
                             <CustNum xsi:type="xsd:string">4610866</CustNum>
                             <UpdateData SOAP-ENC:arrayType="ns1:FieldValue[4]" xsi:type="ns1:FieldValueArray">
                                    <item xsi:type="ns1:FieldValue">
                                         <Field xsi:type="xsd:string">CustomerID</Field>
                                         <Value xsi:type="xsd:string">55555</Value>
                                    </item>
                                    <item xsi:type="ns1:FieldValue">
                                         <Field xsi:type="xsd:string">CardExp</Field>
                                         <Value xsi:type="xsd:string">0919</Value>
                                    </item>
                                    <item xsi:type="ns1:FieldValue">
                                         <Field xsi:type="xsd:string">CardNumber</Field>
                                         <Value xsi:type="xsd:string">4000100911112225</Value>
                                    </item>
                                    <item xsi:type="ns1:FieldValue">
                                         <Field xsi:type="xsd:string">Amount</Field>
                                         <Value xsi:type="xsd:string">80.50</Value>
                                    </item>
                             </UpdateData>
                        </ns1:quickUpdateCustomer>
                 </SOAP-ENV:Body>
            </SOAP-ENV:Envelope>   

Example Response

<?xml version="1.0" encoding="utf-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ns1="urn:usaepay"
     xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <SOAP-ENV:Body>
        <ns1:quickUpdateCustomerResponse>
          <quickUpdateCustomerReturn xsi:type="xsd:boolean">true</quickUpdateCustomerReturn>
        </ns1:quickUpdateCustomerResponse>
      </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Update customer data in selected fields only.

This method allows you to update only specified data for a customer record, rather than replacing all existing data. Fields that can be changed using this method include a customer's contact information, as well as customized notes on their account and information regarding any recurring billing cycle that they have been enabled for, such as the amount to be billed, and the number of transactions remaining.

This method requires the use of the CustNum, a unique customer number assigned by the gateway. If you have lost or cannot remember the customer's CustNum, use the searchCustomers method to find the correct CustNum.

This method uses the UpdateData array containing the fields that you would like to update. The "key" of each element is the name of the field you wish to change and the "value" of the element is the new value that you would like to assign.

The following fields may be updated using this method:

FirstName Address Enabled
CustomerID City Schedule
Card Number State Next
CardExp Zip NumLeft
Account Country Amount
Routing Phone ReceiptNote
CheckFormat fax SendReceipt
CustomData Email Notes
Source URL Description
User OrderID

Related Methods

Syntax

boolean quickUpdateCustomer ( ueSecurityToken Token, string CustNum, FieldValue UpdateData )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
CustNum string A unique customer number assigned by the gateway
UpdateData array Array of FieldValue objects to be updated.

Response Parameters

Name Type Description
quickUpdateCustomerReturn boolean Returns confirmation of request only if successful. If request fails, an exception will be thrown

Change Log

Version Change
1.7 Changed CustNum to type string
1.1 Method added prior to v1.1

copyCustomer

Example Request

    <?php
try {

      // CustNum for Customer to Copy  
      $CustNum="12345678";

      // $toMerchToken is setup with sourcekey
      // for merchant being copied to
      $NewCustNum=$client->copyCustomer($token, $CustNum,$toMerchToken);

    } catch(Exception $e)  {

      echo 'Error: ' . $e->getMessage();

    }
        ?>

try {

      //CusNum From Customer to copy
      BigInteger CustNum = BigInteger("12345678");

      // toMerchToken is the token setup with a source key
      // for the merchant being copied to.
      BigInteger NewCustNum = client.copyCustomer(token, CustNum, toMerchToken);

    } catch (Exception e) {
      System.out.println("Soap Exception: " + e.getMessage());
    }

Dim token1 As usaepay.ueSecurityToken
            Dim token2 As usaepay.ueSecurityToken

            token1 = Me.CreateToken("source key of the merchant1", "1234")
            token2 = Me.CreateToken("source key of the merchant2", "1234")

            Dim custNum As String
            custNum = "103125"
            Dim NewCust As String

            NewCust = client.copyCustomer(token1, custNum, token2)
            MsgBox(NewCust)

usaepay.ueSecurityToken totoken = new usaepay.ueSecurityToken();
                usaepay.ueHash hash = new usaepay.ueHash();
                string sourcekey = "NEW SOURCE KEY";
                string pin = "new pin";
                totoken.SourceKey = sourcekey;

                hash.Type = "md5";
                hash.Seed = Guid.NewGuid().ToString();

                string prehashvalue = string.Concat(token.SourceKey, hash.Seed, pin);
                hash.HashValue = GenerateHash(prehashvalue);

                totoken.PinHash = hash;

                string CustNum = "89147";
                string NewCust;

                try
                {
                    NewCust = client.copyCustomer(token, CustNum, totoken);
                    MessageBox.Show(string.Concat(NewCust));
                }

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

This method allows you to copy a customer record from one merchant to another. This method is only available to merchants who have a master user setup to access both accounts.

Syntax

CustNum copyCustomer ( ueSecurityToken Token, string CustNum )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
CustNum string A unique customer number assigned by the gateway
%ueSecurityToken% object Merchant security token: used to identify the merchant that the customer is being copied to.

Return Value

Name Type Description
CustNum string Returns gateway assigned Customer Number of the new customer.

Change Log

Version Description
1.7 Changed ReturnValue to type string

moveCustomer

Example Request

try {
      //Set CustNum to the customer number that you want to move.  "merch2token"
      //represents a token set up under the merchant the customer is being moved to.
      BigInteger CustNum = new BigInteger("123456");
      BigInteger NewCustNum = client.moveCustomer(token, CustNum, merch2token);

      System.out.println(NewCustNum);
    } catch (Exception e) {
        System.out.println("Soap Exception: " + e.getMessage());
    }

Dim client As usaepay.usaepayService = New usaepay.usaepayService
            Dim token1 As usaepay.ueSecurityToken
            Dim token2 As usaepay.ueSecurityToken

            token1 = Me.CreateToken("source key of the merchant1", "1234")
            token2 = Me.CreateToken("source key of the merchant2", "1234")

            Dim custNum As String
            custNum = "103125"
            Dim NewCust As String

            NewCust = client.moveCustomer(token1, custNum, token2)
            MsgBox(NewCust)

usaepay.ueSecurityToken totoken = new usaepay.ueSecurityToken();
                usaepay.ueHash hash = new usaepay.ueHash();
                string sourcekey = "NEW SOURCE KEY";
                string pin = "new pin";
                totoken.SourceKey = sourcekey;

                hash.Type = "md5";
                hash.Seed = Guid.NewGuid().ToString();

                string prehashvalue = string.Concat(token.SourceKey, hash.Seed, pin);
                hash.HashValue = GenerateHash(prehashvalue);

                totoken.PinHash = hash;

                string CustNum = "89147";
                string NewCust;

                try
                {
                    NewCust = client.moveCustomer(token, CustNum, totoken);
                    MessageBox.Show(string.Concat(NewCust));
                }

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

This method allows you to move a customer record from one merchant to another. This method is only available to merchants who have a master user setup to access both accounts. The move method copies the customer to new merchant and then deletes the original customer. A new CustNum is assigned.

Syntax

CustNum moveCustomer ( ueSecurityToken FromToken, string CustNum, ueSecurityToken ToToken)

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
CustNum string A unique customer number assigned by the gateway
%ueSecurityToken% object Merchant security token: used to identify the merchant that the customer is being migrated to.

Return Value

Name Type Description
CustNum string Returns gateway assigned Customer Number of the new customer.

Change Log

Version Description
1.7 Changed CustNum and ReturnValue to type string

Pay Methods

addCustomerPaymentMethod

Example Request

    <?php
    try {

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

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

        'SecondarySort'=>0
        );

      $Default=true;
      $Verify=false;

      $MethodID=$client->addCustomerPaymentMethod($token, $CustNum, $PaymentMethod,
                                             $Default, $Verify);


    }

    catch(SoapFault $e) {

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

    }
        ?>

    try {

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

    //Setting up New Payment Method
    PaymentMethod paymethod = new PaymentMethod();
        paymethod.setExpires("2012-09-01");
        CreditCardData ccdata = new CreditCardData();
            ccdata.setCardNumber("4000100011112224");
            ccdata.setCardExpiration("0912");
            ccdata.setAvsStreet("123 Main");
            ccdata.setAvsZip("12345");
        paymethod.setCreditCardData(ccdata);
        paymethod.setMethodName("My Visa");


    //Adding Payment Method
    BigInteger PaymentMethodID = client.addCustomerPaymentMethod(token, custnum, paymethod, true, true);

    } catch (Exception e) {
        System.out.println("Soap Exception: " + e.getMessage());
    }

    Dim CustNum As String
            CustNum = "103125"

            Dim payMethod As usaepay.PaymentMethod = New usaepay.PaymentMethod
            payMethod.CardExpiration = "1212"
            payMethod.CardNumber = "4000100011112224"
            payMethod.AvsStreet = "123 Main st."
            payMethod.AvsZip = "90046"
            payMethod.MethodName = "My Visa"

            Dim response As String

            response = client.addCustomerPaymentMethod(token, CustNum, payMethod, False, True)
            MsgBox(response)

                string CustNum = "89792";            

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

                string response;

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

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

    <?xml version="1.0" encoding="UTF-8"?>
       <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ns1="urn:usaepay"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
        SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
          <SOAP-ENV:Body>
             <ns1:addCustomerPaymentMethod>
                <Token xsi:type="ns1:ueSecurityToken">
                   <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
                   <PinHash xsi:type="ns1:ueHash">
                      <HashValue xsi:type="xsd:string">822928da5a6ca1e93b432055cc2007617b481cd8</HashValue>
                      <Seed xsi:type="xsd:string">12036339087-test</Seed>
                      <Type xsi:type="xsd:string">sha1</Type>
                   </PinHash>
                   <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
                </Token>
                <CustNum xsi:type="xsd:string">4608142</CustNum>
                <PaymentMethod xsi:type="ns1:PaymentMethod">
                   <MethodName xsi:type="xsd:string">CreditCard</MethodName>
                   <SecondarySort xsi:type="xsd:integer">8</SecondarySort>
                   <AvsStreet xsi:type="xsd:string">5454 Bravo St</AvsStreet>
                   <AvsZip xsi:type="xsd:string">91111</AvsZip>
                   <CardCode xsi:type="xsd:string"></CardCode>
                   <CardExpiration xsi:type="xsd:string">1218</CardExpiration>
                   <CardNumber xsi:type="xsd:string">4444555566667779</CardNumber>
                   <CardType xsi:type="xsd:string"></CardType>
                </PaymentMethod>
                <MakeDefault xsi:type="xsd:boolean">true</MakeDefault>
                <Verify xsi:type="xsd:boolean">false</Verify>
             </ns1:addCustomerPaymentMethod>
          </SOAP-ENV:Body>
       </SOAP-ENV:Envelope>

Example Response

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

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

Multiple payment methods may be stored for each customer. There is no limit to the number of payment methods that can be stored, but only one of these methods may be marked as the default payment method for all future transactions including recurring billing and manual charges.

To set a payment method as default, pass "true" for the MakeDefault parameter. Setting a payment method to default overrides the SecordarySort parameter and sets it to 0. If another method is currently set to default, it will have its SecondarySort changed to 1.

All new payment methods will be validated by the system to be sure that the information entered fits the required format for the specified payment method. (ie: Does the credit card have 16 digits and a future expiration date? Does the check routing number have 9 digits?)

To further verify that a credit card is "good", set the Verify parameter to "true" (available for credit cards only). This setting will cause the gateway to run an AuthOnly transaction for $0.05. Any fraud modules that are configured for the source will be run. If the transaction is declined the payment method will not be stored and a fault will be thrown with the decline or error message.

If the Verify parameter is set to "false," the payment data will still be checked to ensure that it is formatted correctly, but the credit card validity will not be verified.

If any errors are detected or the Verify fails, a fault will be thrown. This method requires the use of the CustNum, a unique customer number assigned by the gateway. If you have lost or cannot remember the customer's CustNum, use the searchCustomers method to find the correct CustNum.

Related Methods

Syntax

string runSale ( ueSecurityToken Token, string CustNum, PaymentMethod Payment Method, boolean MakeDefault, boolean Verify )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
CustNum string A unique customer number assigned by the gateway
%PaymentMethod% object Includes method name, description, ID, and expiration date.
MakeDefault boolean Determines default payment method for specified customer. If set to true, payment method will be marked as default.
Verify boolean If set to true, an AuthOnly verification of the credit card validity will be run.

Response Parameters

Name Type Description
addCustomerPaymentMethodReturn string The ID of the new payment method.

setDefaultPaymentMethod

Example Request

<?php

try {
  //Set CustNum for the Customer that you
  //want to delete a payment method from
  $CustNum="12345678"

  //Set PayID for the Payment Method ID
  //that you want to delete
  $PayID="7654321"

  // Delete the payment method
  $Result=$client->setDefaultPaymentMethod($token, $CustNum, $PayID);
}

catch(Exception $e) {
  echo 'Error: ' . $e->getMessage();
}
    ?>

This method makes a specific payment method the default for a customer.

Each customer record may contain multiple payment methods. (Exception: see Beta6 note below.) This option allows you to remove expired or unused payment methods from your customer's records.

New payment methods may be added by using addCustomerPaymentMethod.

This method requires the use of the CustNum, a unique customer number assigned by the gateway. If you have lost or cannot remember the customer's CustNum, use the searchCustomers method to find the correct CustNum.

Related Methods

Syntax

boolean setDefaultPaymentMethod ( ueSecurityToken Token, string Custnum, string PaymentMethodID)

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
CustNum string System assigned CustNum of stored customer record.
PaymentMethodID string System assigned id of stored customer payment method.

Response Parameters

Name Type Description
setDefaultPaymentMethodReturn boolean Returns confirmation of that payment method was set to default. If this fails, an exception will be thrown.

deleteCustomerPaymentMethod

Example Request

<?php
        try {
      //Set CustNum for the Customer that you
      //want to delete a payment method from
      $CustNum="12345678"

      //Set PayID for the Payment Method ID
      //that you want to delete
      $PayID="7654321"

      // Delete the payment method
      $Result=$client->deleteCustomerPaymentMethod($token, $CustNum, $PayID);
    } catch(Exception $e) {
      echo 'Error: ' . $e->getMessage();
    }
    ?>

    try {
      //Set CustNum for the Customer that you
      //want to delete a payment method from
      BigInteger custnum = new BigInteger("12345678");

      //Set PayID for the Payment Method ID
      //that you want to delete
      BigInteger PayID = new BigInteger("7654321");

      boolean Result = client.deleteCustomerPaymentMethod(token, CustNum, PayID);
    } catch (Exception e) {
        System.out.println("Soap Exception: " + e.getMessage());
    }

    Dim CustNum As String
            CustNum = "103125"
            Dim PaymentID As String
            PaymentID = "41"

            Dim response As Boolean

            response = client.deleteCustomerPaymentMethod(token, CustNum, PaymentID)
            MsgBox(response)

                string CustNum = "89792";
                string PaymentID = "21";

               Boolean response;

                try
                {
                    response = client.deleteCustomerPaymentMethod(token, CustNum, PaymentID);
                    MessageBox.Show(string.Concat(response));
                }

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

    <?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:deleteCustomerPaymentMethod>
    <Token xsi:type="ns1:ueSecurityToken">
    <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
    <PinHash xsi:type="ns1:ueHash">
    <HashValue xsi:type="xsd:string">3d3a48eb1887857ae8bcb74a8e106ffecd7127de</HashValue>
    <Seed xsi:type="xsd:string">1782568488-test</Seed>
    <Type xsi:type="xsd:string">sha1</Type>
    </PinHash>
    <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
    </Token>
    <Custnum xsi:type="xsd:string">4608157</Custnum>
    <PaymentMethodID xsi:type="xsd:string">163</PaymentMethodID>
    </ns1:deleteCustomerPaymentMethod>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Example Response

    <?xml version="1.0" encoding="utf-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:deleteCustomerPaymentMethodResponse>
    <deleteCustomerPaymentMethodReturn xsi:type="xsd:boolean">true</deleteCustomerPaymentMethodReturn>
    </ns1:deleteCustomerPaymentMethodResponse>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Delete a payment method from an existing customer.

This method removes a stored payment method from a customer's record.

Each customer record may contain multiple payment methods. (Exception: see Beta6 note below.) This option allows you to remove expired or unused payment methods from your customer's records.

New payment methods may be added by using addCustomerPaymentMethod.

This method requires the use of the CustNum, a unique customer number assigned by the gateway. If you have lost or cannot remember the customer's CustNum, use the searchCustomers method to find the correct CustNum.

Please Note: Beta6 supports only one payment method for each customer. This means that if you delete a payment method from a customer's account without adding a new method, the customer will be left with no existing payment methods.

Related Methods

Syntax

boolean deleteCustomerPaymentMethod ( ueSecurityToken Token, string CustNum, string PaymentMethodID )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
CustNum string System assigned CustNum of stored customer record.
PaymentMethodID string System assigned id of stored customer payment method.

Response Parameters

Name Type Description
deleteCustomerPaymentMethodReturn boolean Returns confirmation of payment method deletion only if successful. If deletion fails, an exception will be thrown.

getCustomerPaymentMethod

Example Request

    <?php
try {

   $custnum = '532';
   $methodid = '1234';
   $paymethod = $client->getCustomerPaymentMethod($token,$custnum,$methodid);

   print_r($paymethod);

   echo $paymethod->MethodName . "\n";

} catch(SoapFault $e) {

     echo $e->getMessage();
     echo "\n\nRequest: " . $client->__getLastRequest();
     echo "\n\nResponse: " . $client->__getLastResponse();
}
    ?>

try {
      //Set custnum to the Customer Number of customer you
      //want to retrieve a payment method from.
      BigInteger custnum = new BigInteger("12345678");

      //Set PayID to the Payment Method ID of the
      //Payment Method you want to retrieve.
      BigInteger PayID = new BigInteger("654321");

      PaymentMethod PayMethod = new PaymentMethod();
      PayMethod = client.getCustomerPaymentMethod(token, custnum, PayID);
    } catch (Exception e) {
        System.out.println("Soap Exception: " + e.getMessage());
    }



    Dim CustNum As String
            CustNum = "103125"
            Dim MethodID As String
            MethodID = "39"

            Dim Method As usaepay.PaymentMethod = New usaepay.PaymentMethod

            Method = client.getCustomerPaymentMethod(token, CustNum, MethodID)
            MsgBox(Method.Created)

string CustNum = "89147";
        string MethodID = "19";

        usaepay.PaymentMethod Method = new usaepay.PaymentMethod();

        try {
            Method = client.getCustomerPaymentMethod(token, CustNum, MethodID);
            MessageBox.Show(string.Concat(Method.Created));
        }

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

<?xml version="1.0" encoding="UTF-8"?>
   <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:ns1="urn:usaepay" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
   <SOAP-ENV:Body>
   <ns1:getCustomerPaymentMethod>
   <Token xsi:type="ns1:ueSecurityToken">
   <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
   <PinHash xsi:type="ns1:ueHash">
   <HashValue xsi:type="xsd:string">cb0d69fef422f746976fa6eceef0cc2535fa6263</HashValue>
   <Seed xsi:type="xsd:string">1753029979-test</Seed>
   <Type xsi:type="xsd:string">sha1</Type>
   </PinHash>
   <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
   </Token>
   <CustNum xsi:type="xsd:string">4608985</CustNum>
   <MethodID xsi:type="xsd:string">178</MethodID>
   </ns1:getCustomerPaymentMethod>
   </SOAP-ENV:Body>
   </SOAP-ENV:Envelope>

Example Response

<?xml version="1.0" encoding="utf-8"?>
   <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:ns1="urn:usaepay"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
   <SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
   <SOAP-ENV:Body>
   <ns1:getCustomerPaymentMethodResponse>
   <getCustomerPaymentMethodReturn xsi:type="ns1:PaymentMethod">
   <MethodType xsi:type="xsd:string">cc</MethodType>
   <MethodID xsi:type="xsd:string">178</MethodID>
   <MethodName xsi:type="xsd:string">CreditCard</MethodName>
   <SecondarySort xsi:type="xsd:integer">8</SecondarySort>
   <Created xsi:type="xsd:dateTime">2015-12-09T11:08:20+08:00</Created>
   <Modified xsi:type="xsd:dateTime">2015-12-09T11:08:20+08:00</Modified>
   <AvsStreet xsi:type="xsd:string">5454 Bravo St</AvsStreet>
   <AvsZip xsi:type="xsd:string">91111</AvsZip>
   <CardExpiration xsi:type="xsd:string">2018-12</CardExpiration>
   <CardNumber xsi:type="xsd:string">XXXXXXXXXXXX7779</CardNumber>
   <CardType xsi:type="xsd:string">V</CardType>
   </getCustomerPaymentMethodReturn>
   </ns1:getCustomerPaymentMethodResponse>
   </SOAP-ENV:Body>
   </SOAP-ENV:Envelope>

This method allows you to retrieve a specific payment method stored for a particular customer.

This method requires the use of the CustNum, a unique customer number assigned by the gateway. If you have lost or cannot remember the customer's CustNum, use the (#searchcustomers) method to find the correct CustNum.

You must also specify the MethodID for the desired Payment Method. This MethodID is assigned by the gateway and returned by (#addcustomerpaymentmethod). You can also obtain the methodid from the MethodID property of the PaymentMethod object. This is returned by either getCustomer or (#getcustomerpaymentmethods).

Related Methods

Syntax

PaymentMethod getCustomerPaymentMethod ( ueSecurityToken Token, string CustNum, string Method ID )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
CustNum string A unique customer number assigned by the gateway
MethodID string Unique payment method ID assigned by the gateway.

Response Parameters

Name Type Description
%PaymentMethod% object Includes method name, description, ID, and expiration date.

Change Log

Version Description
1.7 Changed CustNum and PaymentMethodID to type string
1.2 The getPaymentMethod method was added in release 1.2

updateCustomerPaymentMethod

Example Request

<?php

   try {


     $PaymentMethod=array(
       'MethodID' => '375',
       'MethodName'=>'',
       'CardNumber'=>'XXXXXXXXXXXX7779',
       'CardExpiration'=>'2013-02',
       'CardType'=>'',
       'CardCode'=>'',
       'AvsStreet'=>'',
       'AvsZip'=>'',
       'CardPresent'=>'',
       'MagStripe'=>'',
       'TermType'=>'',
       'MagSupport'=>'',
       'XID'=>'',
       'CAVV'=>'',
       'ECI'=>'',
       'InternalCardAuth'=>'',
       'Pares'=>'',
       'SecondarySort'=>0,
       );

     $Verify=false;

     $res=$client->updateCustomerPaymentMethod($token,$PaymentMethod,$Verify);

     $this->assertTrue($res>0, 'Positive PaymentMethodID');

     print_r($res);

   }

   catch(SoapFault $e) {

     echo "\n\nResponse: " . $tran->__getLastResponse();
     die("soap fault: " .$e->getMessage());
     echo "SoapFault: " .$e->getMessage();

     print_r($e);

     echo "\n\nRequest: " . $tran->__getLastRequest();

   }

   ?>

Dim method As usaepay.PaymentMethod = New usaepay.PaymentMethod

        method.MethodID = "39"
        method.MethodName = "My different"
        method.CardExpiration = "1212"
        method.CardNumber = "4444555566667779"

        Dim verify As Boolean
        verify = True

        Dim response As Boolean

        response = client.updateCustomerPaymentMethod(token, method, verify)
        MessageBox.Show(String.Concat(response))

usaepay.PaymentMethod method = new usaepay.PaymentMethod();

            method.MethodID = "19";
            method.MethodName = "My different";
            method.CardExpiration = "1212";
            method.CardNumber = "4444555566667779";

            Boolean verify = true;
            Boolean response;

            try
            {
                response = client.updateCustomerPaymentMethod(token, method, verify);
                MessageBox.Show(string.Concat(response));
            }

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

<?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:updateCustomerPaymentMethod>
    <Token xsi:type="ns1:ueSecurityToken">
    <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
    <PinHash xsi:type="ns1:ueHash">
    <HashValue xsi:type="xsd:string">ad0d6fd9b98dae47ad7055cb913fba200ed483e1</HashValue>
    <Seed xsi:type="xsd:string">1160851186-test</Seed>
    <Type xsi:type="xsd:string">sha1</Type>
    </PinHash>
    <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
    </Token>
    <PaymentMethod xsi:type="ns1:PaymentMethod">
    <MethodID xsi:type="xsd:string">292</MethodID>
    <MethodName xsi:type="xsd:string">Work visa</MethodName>
    <SecondarySort xsi:type="xsd:integer">0</SecondarySort>
    <AvsStreet xsi:type="xsd:string">2828 vida st</AvsStreet>
    <AvsZip xsi:type="xsd:string">94444</AvsZip>
    <CardExpiration xsi:type="xsd:string">2019-02</CardExpiration>
    <CardNumber xsi:type="xsd:string">4000100711112227</CardNumber>
    </PaymentMethod>
    <Verify xsi:type="xsd:boolean">false</Verify>
    </ns1:updateCustomerPaymentMethod>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Example Response

<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:updateCustomerPaymentMethodResponse>
<updateCustomerPaymentMethodReturn xsi:type="xsd:boolean">true</updateCustomerPaymentMethodReturn>
</ns1:updateCustomerPaymentMethodResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Updates the existing payment method. PaymentMethod.MethodID is used to determine which payment method to update.

Related Methods

Syntax

string updateCustomerPaymentMethod ( ueSecurityToken Token, PaymentMethod PaymentMethod, boolean Verify )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
%PaymentMethod% object Includes method name, description, ID, and expiration date.
Verify boolean If set to true, an AuthOnly verification of the credit card validity will be run. (See above.)

Response Parameters

Name Type Description
updateCustomerPaymentMethodReturn boolean Returns true if payment method is updated successfully.

Change Log

Version Description
1.2 Method added.

Search Customer Database

searchCustomers

Example Request

<?php

    try {

      $search=array(
        array(
          'Field'=>'amount',  
          'Type'=>'gt',
          'Value'=>'8.00'),

        array(
          'Field'=>'failures',  
          'Type'=>'gt',  
          'Value'=>'0')
        );
      $start=0;
      $limit=10;
      $matchall=true;
      $RefNum=1009411;
      $Sort = "fname";

      $res=$client->searchCustomers($token,$search,$matchall,$start,$limit,$Sort);
      print_r($res);

      $this->assertTrue($res->CustomersMatched>0 && $res->CustomersReturned>0);

    }

    catch (SoapFault $e) {

      die("Search Customers failed :" .$e->getMessage());

    }

    ?>

Dim matchAll As Boolean
            matchAll = True

            Dim search(0) As usaepay.SearchParam

            search(0) = New usaepay.SearchParam()

            search(0).Field = "Created"
            search(0).Type = "Contains"
            search(0).Value = "2010-09-09"

            Dim response As usaepay.CustomerSearchResult = New usaepay.CustomerSearchResult

            response = client.searchCustomers(token, search, matchAll, "0", "10", "fname")
            MsgBox(response.CustomersMatched)

Boolean matchAll;
                matchAll = true;

                usaepay.SearchParam[] search = new usaepay.SearchParam[2];
                search[0] = new usaepay.SearchParam();

                search[0].Field = "Created";
                search[0].Type = "Contains";
                search[0].Value = "2010-08-10";

                usaepay.CustomerSearchResult response = new usaepay.CustomerSearchResult();

                try
                {
                    response = client.searchCustomers(token, search, matchAll, "0", "10", "fname");

                    MessageBox.Show(response.CustomersMatched);

                }


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

<?xml version="1.0" encoding="UTF-8"?>
       <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ns1="urn:usaepay"
       xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
       SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
          <SOAP-ENV:Body>
             <ns1:searchCustomers>
                <Token xsi:type="ns1:ueSecurityToken">
                   <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
                   <PinHash xsi:type="ns1:ueHash">
                      <HashValue xsi:type="xsd:string">1766a93e46bf263b409d0f444b2eb34b00daa035</HashValue>
                      <Seed xsi:type="xsd:string">1345308215-test</Seed>
                      <Type xsi:type="xsd:string">sha1</Type>
                   </PinHash>
                   <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
                </Token>
                <Search SOAP-ENC:arrayType="ns1:SearchParam[1]" xsi:type="ns1:SearchParamArray">
                   <item xsi:type="ns1:SearchParam">
                      <Field xsi:type="xsd:string">customerid</Field>
                      <Type xsi:type="xsd:string">contains</Type>
                      <Value xsi:type="xsd:string">380</Value>
                   </item>
                </Search>
                <MatchAll xsi:type="xsd:boolean">true</MatchAll>
                <Start xsi:type="xsd:integer">0</Start>
                <Limit xsi:type="xsd:integer">9999</Limit>
                <Sort xsi:nil="true"/></ns1:searchCustomers>
             </SOAP-ENV:Body>
          </SOAP-ENV:Envelope>

Example Response

<?xml version="1.0" encoding="utf-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ns1="urn:usaepay"
     xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"xmlns:xsd="http://www.w3.org/2001/XMLSchema"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <SOAP-ENV:Body>
        <ns1:searchCustomersResponse>
          <searchCustomersReturn xsi:type="ns1:CustomerSearchResult">
            <Customers SOAP-ENC:arrayType="ns1:CustomerObject[1]" xsi:type="ns1:CustomerObjectArray">
              <item xsi:type="ns1:CustomerObject">
                <Amount xsi:type="xsd:double">44.93</Amount>
                <BillingAddress xsi:type="ns1:Address">
                  <City xsi:type="xsd:string">Los Angeles</City>
                  <Company xsi:type="xsd:string">Acme Corp</Company>
                  <Country xsi:type="xsd:string">US</Country>
                  <Email xsi:type="xsd:string">joe@example.com</Email>
                  <Fax xsi:type="xsd:string">333-333-3334</Fax>
                  <FirstName xsi:type="xsd:string">John</FirstName>
                  <LastName xsi:type="xsd:string">Doe</LastName>
                  <Phone xsi:type="xsd:string">333-333-3333</Phone>
                  <State xsi:type="xsd:string">CA</State>
                  <Street xsi:type="xsd:string">1234 main st</Street>
                  <Street2 xsi:type="xsd:string">Suite #123</Street2>
                  <Zip xsi:type="xsd:string">12345</Zip>
                </BillingAddress>
                <Created xsi:type="xsd:dateTime">2015-12-07T16:35:00+08:00</Created>
                <Currency xsi:type="xsd:string">0</Currency>
                <CustNum xsi:type="xsd:string">4606627</CustNum>
                <CustomData xsi:type="xsd:string"></CustomData>
                <CustomFields SOAP-ENC:arrayType="ns1:FieldValue[0]" xsi:type="ns1:FieldValueArray" />
                <CustomerID xsi:type="xsd:string">380</CustomerID>
                <Description xsi:type="xsd:string">Weekly Bill</Description>
                <Enabled xsi:type="xsd:boolean">true</Enabled>
                <Failures xsi:type="xsd:int">0</Failures>
                <LookupCode xsi:type="xsd:string"></LookupCode>
                <Modified xsi:type="xsd:dateTime">2015-12-07T16:35:00+08:00</Modified>
                <Next xsi:type="xsd:string">2016-12-01T12:00:00</Next>
                <Notes xsi:type="xsd:string">Testing the soap addCustomer Function</Notes>
                <NumLeft xsi:type="xsd:integer">50</NumLeft>
                <OrderID xsi:type="xsd:string">1698032860</OrderID>
                <PaymentMethods SOAP-ENC:arrayType="ns1:PaymentMethod[1]" xsi:type="ns1:PaymentMethodArray">
                  <item xsi:type="ns1:PaymentMethod">
                    <MethodType xsi:type="xsd:string">cc</MethodType>
                    <MethodID xsi:type="xsd:string">115</MethodID>
                    <MethodName xsi:type="xsd:string">CreditCard</MethodName>
                    <SecondarySort xsi:type="xsd:integer">8</SecondarySort>
                    <Created xsi:type="xsd:dateTime">2015-12-07T16:35:00+08:00</Created>
                    <Modified xsi:type="xsd:dateTime">2015-12-07T16:35:00+08:00</Modified>
                    <CardExpiration xsi:type="xsd:string">2018-12</CardExpiration>
                    <CardNumber xsi:type="xsd:string">XXXXXXXXXXXX7779</CardNumber>
                    <CardType xsi:type="xsd:string">V</CardType>
                  </item>
                </PaymentMethods>
                <PriceTier xsi:type="xsd:string"></PriceTier>
                <ReceiptNote xsi:type="xsd:string">addCustomer test Created Charge</ReceiptNote>
                <Schedule xsi:type="xsd:string">Weekly</Schedule>
                <SendReceipt xsi:type="xsd:boolean">true</SendReceipt>
                <Source xsi:type="xsd:string">Recurring</Source>
                <Tax xsi:type="xsd:double">0</Tax>
                <TaxClass xsi:type="xsd:string"></TaxClass>
                <User xsi:type="xsd:string">(Auto)</User>
                <URL xsi:type="xsd:string"></URL>
              </item>
            </Customers>
            <CustomersMatched xsi:type="xsd:integer">1</CustomersMatched>
            <CustomersReturned xsi:type="xsd:integer">1</CustomersReturned>
            <Limit xsi:type="xsd:integer">1000</Limit>
            <StartIndex xsi:type="xsd:integer">0</StartIndex>
          </searchCustomersReturn>
        </ns1:searchCustomersResponse>
      </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

This method allows you to search the customer database using flexible search terms. This method searches the customer database (aka recurring billing) not the transactions history. To search the transaction history for a specific customer, use either the searchTransactions or getCustomerHistory method.

Use as many or as few search terms as you like. With MatchAll set to "true," all terms must match to return a result. If the search does not yield the desired results, try broadening your search by eliminating terms, or change MatchAll to "false."

Valid field names for search and sort are:

BillingAddress.FirstName Modified Amount
BillingAddress.lastname CustNum Tax
BillingAddress.Company CustomerID Enabled
BillingAddress.Street Created Failures
BillingAddress.Street2 Description Start
BillingAddress.City Notes Next
BillingAddress.State OrderID NumLeft
BillingAddress.Zip Source Schedule
BillingAddress.Country User SendReceipt
BillingAddress.Phone CustomFields ReceiptNote
BillingAddress.Fax
BillingAddress.Email

Related Methods

Syntax

CustomerSearchResult searchCustomers ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string Sort)

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
%SearchParam% array Array of search parameters.
MatchAll boolean If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned.
Start integer Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200)
Limit integer Maximum number of records to return in result set.
Sort string Comma separated list of fields to sort by.

Return Value

Name Type Description
%CustomerSearchResult% object Returns results of customer search based on parameters set. Customers will only show up to 1000 payment methods per customer.

searchCustomerID

Example Request

<?php

    try {

      $CustID = "21021";

      $CustNum = $client->searchCustomerID(token, $CustID);

      $this->assertEquals($CustNum, "1222");

      }

    catch(SoapFault $e) {

      die("soap fault: " .$e->getMessage());         

      }

    ?>

Dim custID As String
            custID = "123456"

            Dim response As String

            response = client.searchCustomerID(token, custID)
            MsgBox(response)

string custID = "123456";

                string response;

                try
                {
                    response = client.searchCustomerID(token, custID);

                        MessageBox.Show(string.Concat("CustNum: ",response));


                }

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

 <?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:searchCustomerID>
    <Token xsi:type="ns1:ueSecurityToken">
    <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
    <PinHash xsi:type="ns1:ueHash">
    <HashValue xsi:type="xsd:string">41e7d8ace19560b582699e53ac83b784c5fe911c</HashValue>
    <Seed xsi:type="xsd:string">11039155194-test</Seed>
    <Type xsi:type="xsd:string">sha1</Type>
    </PinHash>
    <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
    </Token>
    <CustID xsi:type="xsd:string">1861505359</CustID>
    </ns1:searchCustomerID>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Example Response

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

This method allows you to use the CustID - a customer identification number assigned by the merchant at the time the customer account is created - to find the gateway assigned CustNum associated with the customer's stored data.

The CustNum is required for several customer data storage management methods, including addCustomerPaymentMethod, updateCustomer, and deleteCustomer.

Related Methods

Syntax

string searchCustomerID ( ueSecurityToken Token, string CustID )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
CustID string Merchant assigned Customer ID.

Return Value

Name Type Description
CustNum string Returns gateway assigned Customer Number.

searchCustomersCount

Example Request

<?php

    try {

      $search=array(
        array(
          'Field'=>'amount',  
          'Type'=>'gt',
          'Value'=>'8.00'),

        array(
          'Field'=>'failures',  
          'Type'=>'gt',  
          'Value'=>'0')
        );
      $start=0;
      $limit=10;
      $matchall=true;
      $RefNum=1009411;
      $Sort = "fname";

      $res=$client->searchCustomersCount($token,$search,$matchall,$start,$limit,$Sort);
      print_r($res);              
    }

    catch (SoapFault $e) {

      die("Search Customers failed :" .$e->getMessage());

    }

    ?>

Dim matchAll As Boolean
            matchAll = True

            Dim search(0) As usaepay.SearchParam

            search(0) = New usaepay.SearchParam()

            search(0).Field = "Created"
            search(0).Type = "Contains"
            search(0).Value = "2010-09-09"

            Dim response As usaepay.CustomerSearchResult = New usaepay.CustomerSearchResult

            response = client.searchCustomersCount(token, search, matchAll, "0", "10", "fname")
            MsgBox(response.CustomersMatched)

Boolean matchAll;
                matchAll = true;

                string[] fields = new string[3];
                usaepay.SearchParam[] search = new usaepay.SearchParam[2];
                search[0] = new usaepay.SearchParam();

                search[0].Field = "Created";
                search[0].Type = "Contains";
                search[0].Value = "2010-08-10";

                usaepay.CustomerSearchResult response = new usaepay.CustomerSearchResult();

                try
                {
                    response = client.searchCustomersCount(token, search, matchAll, "0", "10", "fname");

                    MessageBox.Show(response.CustomersMatched);

                }


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

Identical to the searchCustomers method except only the customer counts are returned. Like searchCustomers, this method returns CustomerSearchResult. The only difference is that CustomerSearchResult.Customers is left empty. This method provides a quicker way to determine the size of the result set before starting to retrieve the full search results.

Related Methods

Syntax

CustomerSearchResult searchCustomersCount ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string Sort)

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
%SearchParam% array Array of search parameters.
MatchAll boolean If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned.
Start integer Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200)
Limit integer Maximum number of records to return in result set.
Sort string Comma separated list of fields to sort by.

Return Value

Name Type Description
%CustomerSearchResult% object Returns results of customer search based on parameters set.

Change Log

Version Description
1.2 Method added in soap 1.2 release

searchCustomersCustom

Example Request

<?php

    try {

      $search=array(
        array('Field'=>'amount', 'Type'=>'gt','Value'=>'8.00'),
        array('Field'=>'customerid', 'Type'=>'gt', 'Value'=>'0')
        );

      $start=0;
      $limit=10;
      $matchall=true;
      $fieldList = array('CustNum', 'BillingAddress.Company', 'Amount', 'Next');
      $format='csv';
      $Sort='fname';

      $res=$this->client->searchCustomersCustom($this->token,$search,$matchall,$start,$limit,$fieldList,$format,$Sort);
      $res=base64_decode($res);

      print_r($res);

    }

    catch (SoapFault $e) {
      die("Search Customers failed :" .$e->getMessage());

    }

    ?>

Dim matchAll As Boolean
            matchAll = True

            Dim search(0 To 1) As usaepay.SearchParam

            search(0) = New usaepay.SearchParam()

            search(0).Field = "Created"
            search(0).Type = "Contains"
            search(0).Value = "2010-09-09"

            Dim FieldList(0 To 2) As String

            FieldList(0) = "CustNum"
            FieldList(1) = "BillingAddress.Company"
            FieldList(2) = "Amount"

            Dim result As String

            result = client.searchCustomersCustom(token, search, matchAll, "0", "10", FieldList, "csv", "fname")
            Dim binaryData() As Byte
            binaryData = Convert.FromBase64String(result)

            MsgBox(Encoding.UTF8.GetString(binaryData))

Boolean matchAll = true;

                usaepay.SearchParam[] search = new usaepay.SearchParam[2];
                search[0] = new usaepay.SearchParam();

                search[0].Field = "Created";
                search[0].Type = "Contains";
                search[0].Value = "2010-08-10";

                string[] FieldList = new string[3];
                FieldList[0] = "CustNum";
                FieldList[1] = "BillingAddress.Company";
                FieldList[2] = "Amount";

                string result;

                try
                {
                    result = client.searchCustomersCustom(token, search, matchAll, "0", "10", FieldList, "csv", "fname");
                    Byte[] binaryData = new Byte[3];
                    binaryData = Convert.FromBase64String(result);

                    MessageBox.Show(Encoding.UTF8.GetString(binaryData));

                }


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

<?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:searchCustomersCustom>
    <Token xsi:type="ns1:ueSecurityToken">
    <ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
    <PinHash xsi:type="ns1:ueHash">
    <HashValue xsi:type="xsd:string">6e62ffd4cbf1aaa659912f4444122e0b66ed2bd4</HashValue>
    <Seed xsi:type="xsd:string">12966001102012554704</Seed>
    <Type xsi:type="xsd:string">sha1</Type>
    </PinHash>
    <SourceKey xsi:type="xsd:string">(Your Source Key Here)</SourceKey>
    </Token>
    <Search SOAP-ENC:arrayType="ns1:SearchParam[2]" xsi:type="ns1:SearchParamArray">
    <item xsi:type="ns1:SearchParam">
    <Field xsi:type="xsd:string">amount</Field>
    <Type xsi:type="xsd:string">gt</Type>
    <Value xsi:type="xsd:string">8.00</Value>
    </item>
    <item xsi:type="ns1:SearchParam">
    <Field xsi:type="xsd:string">customerid</Field>
    <Type xsi:type="xsd:string">gt</Type>
    <Value xsi:type="xsd:string">0</Value>
    </item>
    </Search>
    <MatchAll xsi:type="xsd:boolean">true</MatchAll>
    <Start xsi:type="xsd:integer">0</Start>
    <Limit xsi:type="xsd:integer">10</Limit>
    <FieldList SOAP-ENC:arrayType="xsd:string[5]" xsi:type="ns1:stringArray">
    <item xsi:type="xsd:string">CustNum</item>
    <item xsi:type="xsd:string">BillingAddress.Company</item>
    <item xsi:type="xsd:string">Amount</item>
    <item xsi:type="xsd:string">Next</item>
    <item xsi:type="xsd:string">CustomData</item>
    </FieldList>
    <Format xsi:type="xsd:string">csv</Format>
    <Sort xsi:nil="true"/></ns1:searchCustomersCustom>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

This method allows you to search the customer database using flexible search terms. This method searches the customer database (aka recurring billing) not the transactions history. To search the transaction history for a specific customer, use either the searchTransactions or getCustomerHistory method.

Use as many or as few search terms as you like. With MatchAll set to "true," all terms must match to return a result. If the search does not yield the desired results, try broadening your search by eliminating terms, or change MatchAll to "false."

Valid field names for search, sort and return are:

BillingAddress.FirstName Modified Amount
BillingAddress.lastname CustNum Tax
BillingAddress.Company CustomerID Enabled
BillingAddress.Street Created Failures
BillingAddress.Street2 Description Start
BillingAddress.City Notes Next
BillingAddress.State OrderID NumLeft
BillingAddress.Zip Source Schedule
BillingAddress.Country User SendReceipt
BillingAddress.Phone CustomFields ReceiptNote
BillingAddress.Fax
BillingAddress.Email

Related Methods

Syntax

string searchCustomersCustom ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string FieldList, string Format, string Sort)

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
%SearchParam% array Array of search parameters.
MatchAll boolean If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned.
Start integer Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200)
Limit integer Maximum number of records to return in result set.
Sort string Comma separated list of fields to sort by.
FieldList list List of fields to return in search.
Format string Specify format of return data. Possible formats include: csv, tab, xml, php, json.

Return Value

Name Type Description
searchCustomersCustomReturn string Base64 encode result set. Returns all of the fields from any customers matching your search parameters. Customers will only show up to 1000 payment methods per customer.

Change Log

Version Description
1.2 Added Sort Parameter
1.1 Soap 1.1 Release
1.0 Method added in soap v1.0

getCustomerHistory

Example Request

    <?php
    try {

      $custnum='547';
      print_r($client->getCustomerHistory($token,$custnum));

    }

    catch(SoapFault $e) {

      echo $e->getMessage();

    }

    echo "\n\nRequest: " . $client->__getLastRequest();
    echo "\n\nResponse: " . $client->__getLastResponse();

    ?>

try {
  //Set CustNum to the Customer Number of customer you
  //want to retrieve a transaction history from.
  BigInteger CustNum = new BigInteger;

  TransactionSearchResult CustHist = new TransactionSearchResult();
  CustHist = client.getCustomerHistory(token, CustNum);
} catch (Exception e) {
    System.out.println("Soap Exception: " + e.getMessage());
}


    Dim CustNum As String
            CustNum = "103125"

            Dim tran As usaepay.TransactionSearchResult
            tran = New usaepay.TransactionSearchResult

            tran = client.getCustomerHistory(token, CustNum)
            MsgBox(tran.SalesCount)

string CustNum = "89147";

            usaepay.TransactionSearchResult tran = new usaepay.TransactionSearchResult();

            try
            {

                tran = client.getCustomerHistory(token, CustNum);
                MessageBox.Show(string.Concat(tran.SalesCount));

            }

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

This method allows you to view all of the transactions completed for a particular customer.

This method requires the use of the CustNum, a unique customer number assigned by the gateway. If you have lost or cannot remember the customer's CustNum, use the (#searchcustomers) method to find the correct CustNum.

Related Methods

Syntax

TransactionSearchResult getCustomerHistory ( ueSecurityToken Token, string CustNum )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
CustNum string A unique customer number assigned by the gateway
Start integer Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200)
Limit integer Maximum number of records to return in result set. Largest Limit allowed is 1000.

Response Parameters

Type Description
%TransactionSearchResult% Returns the results of the customer transaction history search.

Change Log

Version Description
1.6 Added start and limit parameters
1.7 Changed CustNum to type string

Customer Transactions

convertTranToCust

Example Request

    <?php
try {
 // Set RefNum to the Reffernce Num of the
 //transaction you want to convert to a customer
 $RefNum="123456789";

 // Creating customer, saving exact time and verifying customer was created.
 $RecurringBillData = array(
   array('Field'=>'NumLeft', 'Value'=>'10'),
   array('Field'=>'Amount', 'Value'=>'7.40'),
   array('Field'=>'Description', 'Value'=>'Monthly Bill'),
   array('Field'=>'Schedule', 'Value'=>'Monthly'),
   array('Field'=>'Enabled', 'Value'=>'Yes'),
 );

 $custnum = $client->convertTranToCust($token, $RefNum, $RecurringBillData);
}  catch(Exception $e) {
 echo 'Error: ' . $e->getMessage();
}
?>

try {

//Transaction Reffernce Number to convert to a customer
BigInteger RefNum = new BigInteger('123456');

//Setting up the Field Value array for updated data specific to the customer
FieldValueArray UpdateData = new FieldValueArray();
UpdateData.add(new FieldValue("Schedule", "weekly"));
UpdateData.add(new FieldValue("NumLeft", "7"));

//Converting to a customer
BigInteger CustNum = client.convertTranToCust(token, RefNum,UpdateData);

} catch (Exception e) {
    System.out.println("Soap Exception: " + e.getMessage());
}

Dim refnum As String
        refnum = "46978031"
        Dim update(0 To 1) As usaepay.FieldValue
        For i As Integer = 0 To 1
            update(i) = New usaepay.FieldValue
        Next

        update(0).Field = "Schedule"
        update(0).Value = "weekly"
        update(1).Field = "NumLeft"
        update(1).Value = "7"

        Dim response As String
        response = client.convertTranToCust(token, refnum, update)
        MsgBox(response)

string refnum = "46978031";
    usaepay.FieldValue[] update = new usaepay.FieldValue[2];
    for (int i = 0; i < 2; i++) {

        update[i] = new usaepay.FieldValue();

    }

    update[0].Field = "Schedule"; update[0].Value = "weekly";
    update[1].Field = "NumLeft"; update[1].Value = "7";

    string response;

    try
    {
        response = client.convertTranToCust(token, refnum, update);

        MessageBox.Show(string.Concat("Customer Number: ",
                    response));

    }


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

This method copies the credit card/check data, card holder name and address information from an existing transaction and uses it to create a new customer record to be stored in the Customer Database. By default, the customer will be created with recurring billing disabled.

The method returns the new CustNum (customer number). Optional customer fields can be created using the UpdateData parameter. See the (#quickupdatecustomer) method for details on what fields may be set.

Only information entered in the original transaction will be saved. To input additional data, use the (#updatecustomer) or (#quickupdatecustomer) methods. (#updatecustomer) will replace all existing customer data, while (#quickupdatecustomer) allows you to update selected fields only.

Possible fields are:

CustomerID Amount
FirstName Enabled
LastName Next
Company NumLeft
Address Schedule
Address2 SendReceipt
City ReceiptNote
State Card Number
Zip Card Expiration
Country Account Number
Phone Routing Number
Fax Description
Email Notes
URL OrderID
CustomData Source
User

Syntax

string convertTranToCust ( ueSecurityToken Token, string RefNum, FieldValue UpdateData )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
Update array Array of FieldValue objects you would like to update.
RefNum string Unique transaction reference number assigned by the gateway. You can also use TransKey in the RefNum field.

Response Parameters

Name Type Description
CustNum string Returns the gateway generated CustNum of the new customer.

Change Log

Version Description
1.7 TransKey can be used in RefNum field.
1.0 Method added in soap v1.0

runCustomerTransaction

Example Request

<?php
   try {

     $Parameters=array(
      'Command'=>'Sale',
     'Details'=>array(
       'Invoice' => rand(),
       'PONum' => '',
       'OrderID' => '',
       'Description' => 'Sample Credit Card Sale',
       'Amount'=>'1.50' )
       );

     $CustNum='123456';
     $PayMethod='0';

     $res=$client->runCustomerTransaction($token, $CustNum, $PayMethod, $Parameters);
     print_r($res);

   }

   catch (SoapFault $e) {
     echo $client->__getLastRequest();
     echo $client->__getLastResponse();
     die("runCustomerTransaction failed :" .$e->getMessage());

   }

   ?>

Dim custnum As String
          custnum = "103125"
          Dim paymentMethodID As String
          paymentMethodID = "39"

          Dim tran As usaepay.CustomerTransactionRequest = New usaepay.CustomerTransactionRequest

          tran.Details = New usaepay.TransactionDetail

          tran.Details.Invoice = "123456"
          tran.Details.Description = "Sample Credit Card Sale"
          tran.Details.Amount = 1.05
          tran.Details.AmountSpecified = True


          Dim response As usaepay.TransactionResponse
          response = New usaepay.TransactionResponse


          response = client.runCustomerTransaction(token, custnum, paymentMethodID, tran)
          MessageBox.Show(String.Concat(response.Result))

string custNum = "89147";
                string paymentMethodID = "19";
                usaepay.CustomerTransactionRequest tran = new usaepay.CustomerTransactionRequest();
                tran.Details = new usaepay.TransactionDetail();

                tran.Details.Invoice = "123456";
                tran.Details.Description = "Sample Credit Card Sale";
                tran.Details.Amount = 1.05;
                tran.Details.AmountSpecified = true;


                usaepay.TransactionResponse response = new usaepay.TransactionResponse();

                try
                {
                    response = client.runCustomerTransaction(token, custNum, paymentMethodID, tran);
                    MessageBox.Show(string.Concat(response.Result));
                }

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

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:runCustomerTransaction>
 <Token xsi:type="ns1:ueSecurityToken">
 <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
 <PinHash xsi:type="ns1:ueHash">
 <HashValue xsi:type="xsd:string">28294c0d68cd498353c6f6dad03e00a1ac8668e1</HashValue>
 <Seed xsi:type="xsd:string">11688496410-test</Seed>
 <Type xsi:type="xsd:string">sha1</Type>
 </PinHash>
 <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
 </Token>
 <CustNum xsi:type="xsd:string">4600666</CustNum>
 <PaymentMethodID xsi:type="xsd:string">0</PaymentMethodID>
 <Parameters xsi:type="ns1:CustomerTransactionRequest">
 <Command xsi:type="xsd:string">Sale</Command>
 <Details xsi:type="ns1:TransactionDetail">
 <Amount xsi:type="xsd:double">10.5</Amount>
 <Description xsi:type="xsd:string">Sample Credit Card Sale</Description>
 <Invoice xsi:type="xsd:string">327061455</Invoice>
 <OrderID xsi:type="xsd:string"></OrderID>
 <PONum xsi:type="xsd:string"></PONum>
 </Details>
 </Parameters>
 </ns1:runCustomerTransaction>
 </SOAP-ENV:Body>
 </SOAP-ENV:Envelope>

Example Response

<?xml version="1.0" encoding="utf-8"?>
  <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:ns1="urn:usaepay"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
  SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
  <ns1:runCustomerTransactionResponse>
  <runCustomerTransactionReturn xsi:type="ns1:TransactionResponse">
  <AcsUrl xsi:type="xsd:string"></AcsUrl>
  <AuthAmount xsi:type="xsd:double">10.5</AuthAmount>
  <AuthCode xsi:type="xsd:string">144519</AuthCode>
  <AvsResult xsi:type="xsd:string">Address: Match &amp; 5 Digit Zip: Match</AvsResult>
  <AvsResultCode xsi:type="xsd:string">YYY</AvsResultCode>
  <BatchNum xsi:type="xsd:string">211</BatchNum>
  <BatchRefNum xsi:type="xsd:string">198907</BatchRefNum>
  <CardCodeResult xsi:type="xsd:string">Not Processed</CardCodeResult>
  <CardCodeResultCode xsi:type="xsd:string">P</CardCodeResultCode>
  <CardLevelResult xsi:nil="true" />
  <CardLevelResultCode xsi:nil="true" />
  <ConversionRate xsi:type="xsd:double">0</ConversionRate>
  <ConvertedAmount xsi:type="xsd:double">0</ConvertedAmount>
  <ConvertedAmountCurrency xsi:type="xsd:string">0</ConvertedAmountCurrency>
  <CustNum xsi:type="xsd:string">4600666</CustNum>
  <Error xsi:type="xsd:string">Approved</Error>
  <ErrorCode xsi:type="xsd:integer">0</ErrorCode>
  <isDuplicate xsi:type="xsd:boolean">false</isDuplicate>
  <Payload xsi:type="xsd:string"></Payload>
  <RefNum xsi:type="xsd:string">102506029</RefNum>
  <Result xsi:type="xsd:string">Approved</Result>
  <ResultCode xsi:type="xsd:string">A</ResultCode>
  <Status xsi:type="xsd:string">Pending</Status>
  <StatusCode xsi:type="xsd:string">P</StatusCode>
  <VpasResultCode xsi:type="xsd:string"></VpasResultCode>
  </runCustomerTransactionReturn>
  </ns1:runCustomerTransactionResponse>
  </SOAP-ENV:Body>
  </SOAP-ENV:Envelope>

Processes a new transaction using the payment details stored for the customer. This is a one time charge and does not use or affect the recurring billing values, such as amount and description, that have been stored for the customer. The transaction result will be tied to the customer and will be visible in the customer's billing history. The customer does not need to have recurring billing enabled for this method to be used. If you do not have a cardholder listed as part of the payment method, the customer's first and last name in their customer profile will be used as the cardholder.

Related Methods

Syntax

TransactionResponse runCustomerTransaction ( ueSecurityToken Token, string CustNum, string PaymentMethodID )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
CustNum string System assigned CustNum of stored customer record.
PaymentMethodID string System assigned id of stored customer payment method.
%CustomerTransactionRequest% object Transaction amount, invoice number, etc.

Response Parameters

Name Type Description
%TransactionResponse% object Returns a TransactionResponse object containing the results of the transaction and all relevant data.

Change Log

Version Description
1.7 Changed CustNum and PaymentMethodID to type string

Product Methods

Products

addProduct

Example Request

<?php

    try {

    $Product = array(
        "ProductID" => "0-13-508011-8",
        "SKU" =>"135080118",
        "UPC" => "9780135080115",
        "Category" => "Books:Math",
        "Enabled" => true,
        "Name" => "Elementary Differential Equations",
        "Description" => "Rainville, Bedient and Bedient (Eight Edition)",
        "Weight" => 1.0,
        "ShipWeight" => 1.1,
        "Price" => 112.00,
        "ListPrice" =>  128.00,
        "WholesalePrice"=> 100.00,
        "DateAvailable" => "2009-12-01",
        "Manufacturer" => "Prentice Hall",
        "Type" => "Unknown",
        "MinQuantity" =>0,
        "ImageURL" => "http://acme.com/prodimg/123123.jpg",
        "URL" => "http:/acme.com/prod/123123.html"
     );


    $ProductRefNum = $client->addProduct($token, $Product);

      print_r($res);
    }

    catch(SoapFault $e) {

      echo $e->getMessage();

    }

    ?>

Dim product As usaepay.Product = New usaepay.Product
            product.ProductID = "0-13-508011-8"
            product.SKU = "135080118"
            product.UPC = "9780135080115"
            product.Category = "Books:Math"

            Dim inventory(0 To 1) As usaepay.ProductInventory
            inventory(0) = New usaepay.ProductInventory()
            inventory(0).InventoryLocation = "Los angeles"
            inventory(0).QtyOnHand = "10"
            inventory(0).QtyOnOrder = "5"
            inventory(0).DateAvailable = "2010-08-20"

            product.Inventory = inventory

            Dim priceTier(0 To 1) As usaepay.PriceTier
            priceTier(0) = New usaepay.PriceTier()
            priceTier(0).Qty = "2"
            priceTier(0).Price = "100"

            product.PriceTiers = priceTier

            product.TaxClass = "your_tax_class"
            product.Enabled = True
            product.Name = "Elementary Differential Equations"
            product.Description = "Rainville, Bedient and Bedient (Eight Edition)"
            product.Weight = 1.0
            product.ShipWeight = 1.1
            product.Price = 112.0
            product.ListPrice = 128.0
            product.WholesalePrice = 100.0
            product.DateAvailable = "2010-08-01"
            product.Manufacturer = "Prentice Hail"
            product.MinQuantity = "0"

            Dim refNum As String

            refNum = client.addProduct(token, product)
            MsgBox(refNum)

                usaepay.Product product = new usaepay.Product();
                product.ProductID = "0-13-508011-8";
                product.SKU = "135080118";
                product.UPC = "9780135080115";
                product.Category = "Books:Math";

                usaepay.ProductInventory[] inventory = new usaepay.ProductInventory[1];
                inventory[0] = new usaepay.ProductInventory();
                inventory[0].InventoryLocation = "Los angeles";
                inventory[0].QtyOnHand = "10";
                inventory[0].QtyOnOrder = "5";
                inventory[0].DateAvailable = "2010-08-20";

                product.Inventory = inventory;

                usaepay.PriceTier[] priceTier = new usaepay.PriceTier[1];
                priceTier[0] = new usaepay.PriceTier();
                priceTier[0].Qty = "2";
                priceTier[0].Price = "100";

                product.PriceTiers = priceTier;

                product.TaxClass = "your_tax_class";
                product.Enabled = true;
                product.Name = "Elementary Differential Equations";
                product.Description = "Rainville, Bedient and Bedient (Eight Edition)";
                product.Weight = 1.0;
                product.ShipWeight = 1.1;
                product.Price = 112.00;
                product.ListPrice = 128.00;
                product.WholesalePrice = 100.00;
                product.DateAvailable = "2010-08-01";
                product.Manufacturer = "Prentice Hail";
                product.MinQuantity = "0";

                string refNum;

                try
                {
                    refNum = client.addProduct(token, product);
                    MessageBox.Show(string.Concat(refNum));
                }
                catch (Exception err)
                {
                    MessageBox.Show(err.Message);
                }

<?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:addProduct>
<Token xsi:type="ns1:ueSecurityToken">
<ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
<PinHash xsi:type="ns1:ueHash">
<HashValue xsi:type="xsd:string">6336749834eabc43b70de5bc20fe037b6517b8d4</HashValue>
<Seed xsi:type="xsd:string">1667362908-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Product xsi:type="ns1:Product">
<ProductID xsi:type="xsd:string">2345678</ProductID>
<SKU xsi:type="xsd:string">909090</SKU>
<UPC xsi:type="xsd:string">789789</UPC>
<Category xsi:type="xsd:string">liqour</Category>
<Enabled xsi:type="xsd:boolean">true</Enabled>
<Name xsi:type="xsd:string">sailor jerry</Name>
<Description xsi:type="xsd:string">spice rum bottle</Description>
<Model xsi:type="xsd:string">bottle</Model>
<Weight xsi:type="xsd:double">7.7</Weight>
<ShipWeight xsi:type="xsd:double">11.7</ShipWeight>
<Price xsi:type="xsd:double">40</Price>
<WholesalePrice xsi:type="xsd:double">60</WholesalePrice>
<ListPrice xsi:type="xsd:double">20</ListPrice>
<Manufacturer xsi:type="xsd:string">Chase</Manufacturer>
<PhysicalGood xsi:type="xsd:boolean">true</PhysicalGood>
<MinQuantity xsi:type="xsd:integer">18</MinQuantity>
<ImageURL xsi:type="xsd:string">www.candyland.com</ImageURL>
<URL xsi:type="xsd:string">www.candyland.com</URL>
<Inventory SOAP-ENC:arrayType="ns1:ProductInventory[1]" xsi:type="ns1:ProductInventoryArray">
<item xsi:type="ns1:ProductInventory">
<InventoryLocation xsi:type="xsd:string">compton</InventoryLocation>
<QtyOnHand xsi:type="xsd:string">30</QtyOnHand>
<QtyOnOrder xsi:type="xsd:string">10</QtyOnOrder>
<DateAvailable xsi:type="xsd:string">461</DateAvailable>
</item>
</Inventory>
<PriceTiers SOAP-ENC:arrayType="ns1:PriceTier[2]" xsi:type="ns1:PriceTierArray">
<item xsi:type="ns1:PriceTier">
<Qty xsi:type="xsd:string">10</Qty>
<Price xsi:type="xsd:string">25</Price>
</item>
<item xsi:type="ns1:PriceTier">
<Qty xsi:type="xsd:string">20</Qty>
<Price xsi:type="xsd:string">15</Price>
</item>
</PriceTiers>
</Product>
</ns1:addProduct>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Example Response

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

This method creates a new product record and returns a ProductRefNum

The addProduct method creates a new product record. If successful, a ProductRefNum will be returned. The ProductRefNum is a gateway assigned product identifier. This product identifier should be stored and is needed for updating and deleting products. The product database is an optional feature and may not be supported by all merchants. The merchant should check their gateway package to determine if this feature is available to them.

Related Methods

Syntax

string addProduct ( ueSecurityToken Token, Product )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
%Product% object Object contain product details

Response Parameters

Name Type Description
ProductRefNum string Unique gateway generated product id.

Exceptions

Code Message Advice
41001 Unable to create product database Merchant does not have a product database. The feature not be enabled for merchant. Contact customer service and make sure product database feature is enabled.

deleteProduct

Example Request

    <?php

    try {

      $ProductRefNum='919932077432';
      $client->deleteProduct($token, $ProductRefNum);

    }

    catch(SoapFault $e) {

      echo $e->getMessage();

    }

    ?>

 Dim refNum As String
            refNum = "9001169810"
            Dim response As Boolean

            response = client.deleteProduct(token, refNum)
            MsgBox(response)

                string RefNum = "900116982";

                Boolean response;

                try
                {
                    response = client.deleteProduct(token, RefNum);
                    MessageBox.Show(string.Concat(response));
                }
                catch (Exception err)
                {
                    MessageBox.Show(err.Message);
                }

    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:deleteProduct>
    <Token xsi:type="ns1:ueSecurityToken">
    <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
    <PinHash xsi:type="ns1:ueHash">
    <HashValue xsi:type="xsd:string">31fdc81f0d453b90e6896ae62062369a33fade08</HashValue>
    <Seed xsi:type="xsd:string">11821282856-test</Seed>
    <Type xsi:type="xsd:string">sha1</Type>
    </PinHash>
    <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
    </Token>
    <ProductRefNum xsi:type="xsd:string">9001001973</ProductRefNum>
    </ns1:deleteProduct>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Example Response

    <?xml version="1.0" encoding="utf-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:deleteProductResponse>
    <deleteProductReturn xsi:type="xsd:boolean">true</deleteProductReturn>
    </ns1:deleteProductResponse>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

This method deletes an existing product.

This method removes the specified ProductRefNum from the product database. The product is deleted immediately and this operation can not be undone. The ProductRefNum is the gateway assigned product ID that was returned by addProduct. searchProducts can be used to find the ProductRefNum for a product if it is not known.

Related Methods

Syntax

boolean deleteProduct ( ueSecurityToken Token, ProductRefNum )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
ProductRefNum string Product reference number used to delete a product

Response Parameters

Name Type Description
deleteProductReturn boolean Returns true if product has been deleted (on error an exception is thrown).

Exceptions

Code Message Advice
41002 Product Not Found Product specified by ProductRefNum was not found. Make sure the number stored is not truncated or rounded.
41005 Failed to delete product A database fault was encountered while deleting product record. Try operation again or contact support.

updateProduct

Example Request

<?php

    try {
                $Product = array(
                "ProductID" => "0-13-508011-8",
                "SKU" =>"135080118",
                "UPC" => "9780135080115",
                "Category" => "Books:Math",
                "Enabled" => true,
                "Name" => "Elementary Differential Equations",
                "Description" => "Rainville, Bedient and Bedient (Eight Edition)",
                "Weight" => 1.0,
                "ShipWeight" => 1.1,
                "Price" => 112.00,
                "ListPrice" =>  128.00,
                "WholesalePrice"=> 100.00,
                "DateAvailable" => "2009-12-01",
                "Manufacturer" => "Prentice Hall",
                "Type" => "Unknown",
                "MinQuantity" =>0,
                "MaxQuantity" =>10,
                "ImageURL" => "http://acme.com/prodimg/123123.jpg",
                "URL" => "http:/acme.com/prod/123123.html"
            );

            $client->updateProduct($token, $ProductRefNum, $Product);

    }

    catch(SoapFault $e) {

      echo $e->getMessage();

    }

    ?>

    Dim RefNum As String
            RefNum = "9001169810"

            Dim product As usaepay.Product = New usaepay.Product()
            product.ProductID = "0-13-508011-8"
            product.SKU = "135080118"
            product.UPC = "9780135080115"
            product.Category = "Books:Science"
            product.Enabled = True
            product.Name = "Non-Elementary Differential Equations"
            product.Description = "Rainville, Bedient and Bedient (Eight Edition)"
            product.Weight = 1.0
            product.ShipWeight = 1.1
            product.Price = 112.0
            product.ListPrice = 128.0
            product.WholesalePrice = 100.0
            product.DateAvailable = "2010-08-01"
            product.Manufacturer = "Prentice Hail"
            product.MinQuantity = "0"

            Dim response As Boolean

            response = client.updateProduct(token, RefNum, product)
            MsgBox(response)

                string RefNum = "900116982";

                usaepay.Product product = new usaepay.Product();
                product.ProductID = "0-13-508011-8";
                product.SKU = "135080118";
                product.UPC = "9780135080115";
                product.Category = "Books:Science";
                product.Enabled = true;
                product.Name = "Elementary Differential Equations";
                product.Description = "Rainville, Bedient and Bedient (Eight Edition)";
                product.Weight = 1.0;
                product.ShipWeight = 1.1;
                product.Price = 112.00;
                product.ListPrice = 128.00;
                product.WholesalePrice = 100.00;
                product.DateAvailable = "2010-08-01";
                product.Manufacturer = "Prentice Hail";
                product.MinQuantity = "0";

                Boolean response;

                try
                {
                    response = client.updateProduct(token, RefNum, product);
                    MessageBox.Show(string.Concat(response));
                }
                catch (Exception err)
                {
                    MessageBox.Show(err.Message);
                }

    <?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:updateProduct>
    <Token xsi:type="ns1:ueSecurityToken">
    <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
    <PinHash xsi:type="ns1:ueHash">
    <HashValue xsi:type="xsd:string">a6a24337700a018bb569202fefb5e034414f2adf</HashValue>
    <Seed xsi:type="xsd:string">11288967116-test</Seed>
    <Type xsi:type="xsd:string">sha1</Type>
    </PinHash>
    <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
    </Token>
    <ProductRefNum xsi:type="xsd:string">9001001967</ProductRefNum>
    <Product xsi:type="ns1:Product">
    <ProductID xsi:type="xsd:string">866872</ProductID>
    <SKU xsi:type="xsd:string">111111111</SKU>
    <UPC xsi:type="xsd:string">555555555</UPC>
    <Category xsi:type="xsd:string">liqour</Category>
    <Enabled xsi:type="xsd:boolean">true</Enabled>
    <Name xsi:type="xsd:string">Big V</Name>
    <Description xsi:type="xsd:string">vodka</Description>
    <Model xsi:type="xsd:string">bottle</Model>
    <Weight xsi:type="xsd:double">5.7</Weight>
    <ShipWeight xsi:type="xsd:double">11.7</ShipWeight>
    <Price xsi:type="xsd:double">40</Price>
    <WholesalePrice xsi:type="xsd:double">60</WholesalePrice>
    <ListPrice xsi:type="xsd:double">20</ListPrice>
    <Manufacturer xsi:type="xsd:string">Chase</Manufacturer>
    <PhysicalGood xsi:type="xsd:boolean">true</PhysicalGood>
    <MinQuantity xsi:type="xsd:integer">80</MinQuantity>
    <ImageURL xsi:type="xsd:string">www.lime.com</ImageURL>
    <URL xsi:type="xsd:string">www.lime.com</URL>
    <Created xsi:type="xsd:dateTime"/>
    <Modified xsi:type="xsd:dateTime"/>
    <PriceTiers SOAP-ENC:arrayType="ns1:PriceTier[1]" xsi:type="ns1:PriceTierArray">
    <item xsi:type="ns1:PriceTier">
    <Qty xsi:type="xsd:string">10</Qty>
    <Price xsi:type="xsd:string">25</Price>
    </item>
    </PriceTiers>
    </Product>
    </ns1:updateProduct>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Example Response

    <?xml version="1.0" encoding="utf-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:updateProductResponse>
    <updateProductReturn xsi:type="xsd:boolean">true</updateProductReturn>
    </ns1:updateProductResponse>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

This method updates an existing product.

Updates an existing product based on its ProductRefNum. The entire product is replaced by the contents of the Product parameter. Developers can use the getProduct method to retrieve the Product object, modify a field and then post the object back to the server. If you only need to update one field, consider using the quickUpdateProduct method instead.

Related Methods

Syntax

boolean updateProduct ( ueSecurityToken, ProductRefNum, Product )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
ProductRefNum string Unique gateway generated product id.
%Product% object Product data

Response Parameters

Name Type Description
updateProductReturn boolean Returns a true if the product is updated correctly.

Exceptions

Code Message Advice
41002 Product Not Found Product specified by ProductRefNum was not found. Make sure the number stored is not truncated or rounded.
41003 Error saving product A database fault was encountered while saving product record. Try operation again or contact support.

quickUpdateProduct

Update product data in selected fields only.

This method allows you to update only specified data for a product record, rather than replacing all existing data.

This method requires the use of the ProductRefNum, a unique product number assigned by the gateway. If you have lost or cannot remember the products's ProductRefNum, use the searchProducts method to find the correct ProductRefNum.

This method uses the UpdateData array containing the fields that you would like to update. The "key" of each element is the name of the field you wish to change and the "value" of the element is the new value that you would like to assign.

The following fields may be updated using this method:

Type Name Description
ProductID string Merchant assigned product ID
CategoryID integer Merchant assigned category ID.
SKU string Stock-Keeping Unit
UPC string Universal Product Code
Enabled boolean Enables the ability to store products
Name string Name of the product
Description string Product description
Model string Model of the product
Weight double Weight of the product
ShipWeight double Shipping weight of the product
Price double Price of the product
WholesalePrice double Wholesale price of the product
ListPrice double List price of the product
DateAvailable string Date the product is available for sale
Manufacturer string Maker of the product
PhysicalGood boolean Tangible/Shippable good
MinQuantity integer Minimum quantity allowed
MaxQuantity integer Maximum quantity allowed
ImageURL string URL address of the product image
URL string URL of the product

Syntax

boolean quickUpdateProduct ( ueSecurityToken, string ProductRefNum, FieldValue UpdateData )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
UpdateData array Array of FieldValue objects to be updated.
ProductRefNum string A unique product id assigned by the gateway.

Response Parameters

Name Type Description
quickUpdateProductReturn boolean Returns confirmation of request only if successful. If request fails, an exception will be thrown

getProduct

Example Request

    <?php

    try {
      $ProductRefNum = '912093987473';
      $product = $client->getProduct($token, $ProductRefNum);

      print_r($product);
    }

    catch(SoapFault $e) {

      echo $e->getMessage();

    }

    ?>

     Dim prod As usaepay.Product = New usaepay.Product
            Dim refNum As String
            refNum = "9001169811"

            prod = client.getProduct(token, refNum)
            MsgBox(prod.Name)

                string RefNum = "900116985";

                usaepay.Product response = new usaepay.Product();

                try
                {
                    response = client.getProduct(token, RefNum);
                    MessageBox.Show(string.Concat(response.Price));
                }
                catch (Exception err)
                {
                    MessageBox.Show(err.Message);
                }

    <?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:getProduct>
    <Token xsi:type="ns1:ueSecurityToken">
    <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
    <PinHash xsi:type="ns1:ueHash">
    <HashValue xsi:type="xsd:string">720104052fd3b583716a1b18021b4986fee3c482</HashValue>
    <Seed xsi:type="xsd:string">11434035177-test</Seed>
    <Type xsi:type="xsd:string">sha1</Type>
    </PinHash>
    <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
    </Token>
    <ProductRefNum xsi:type="xsd:string">9001001976</ProductRefNum>
    </ns1:getProduct>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Example Response

    <?xml version="1.0" encoding="utf-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:getProductResponse>
    <getProductReturn xsi:type="ns1:Product">
    <ProductRefNum xsi:type="xsd:string">9001001976</ProductRefNum>
    <ProductID xsi:type="xsd:string">2345678</ProductID>
    <SKU xsi:type="xsd:string">909090</SKU>
    <UPC xsi:type="xsd:string">789789</UPC>
    <Category xsi:type="xsd:string">liqour</Category>
    <Enabled xsi:type="xsd:boolean">true</Enabled>
    <Name xsi:type="xsd:string">sailor jerry</Name>
    <Description xsi:type="xsd:string">spice rum bottle</Description>
    <Model xsi:type="xsd:string">bottle</Model>
    <Weight xsi:type="xsd:double">7.7</Weight>
    <ShipWeight xsi:type="xsd:double">11.7</ShipWeight>
    <Price xsi:type="xsd:double">40</Price>
    <WholesalePrice xsi:type="xsd:double">60</WholesalePrice>
    <ListPrice xsi:type="xsd:double">20</ListPrice>
    <DateAvailable xsi:type="xsd:string">0000-00-00</DateAvailable>
    <Manufacturer xsi:type="xsd:string">Chase</Manufacturer>
    <PhysicalGood xsi:type="xsd:boolean">true</PhysicalGood>
    <TaxClass xsi:type="xsd:string">None</TaxClass>
    <MinQuantity xsi:type="xsd:integer">18</MinQuantity>
    <ImageURL xsi:type="xsd:string">www.candyland.com</ImageURL>
    <URL xsi:type="xsd:string">www.candyland.com</URL>
    <Created xsi:type="xsd:dateTime">2015-12-17T14:54:28+08:00</Created>
    <Modified xsi:type="xsd:dateTime">2015-12-17T14:54:28+08:00</Modified>
    <Inventory SOAP-ENC:arrayType="ns1:ProductInventory[0]"
    xsi:type="ns1:ProductInventoryArray" />
    <PriceTiers SOAP-ENC:arrayType="ns1:PriceTier[1]" xsi:type="ns1:PriceTierArray">
    <item xsi:type="ns1:PriceTier">
    <Qty xsi:type="xsd:string">10</Qty>
    <Price xsi:type="xsd:string">25</Price>
    <CustomerTier xsi:type="xsd:string"></CustomerTier>
    </item>
    </PriceTiers>
    </getProductReturn>
    </ns1:getProductResponse>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Retrieve all data for a single product.

This method retrieves the Product object for the product specified by ProductRefNum. The ProductRefNum is the gateway assigned unique product identifier that was returned by addProduct. searchProducts can be used to find the ProductRefNum for a product if it is not known.

The entire Product object is returned.

Related Methods

Syntax

Product getProduct ( ueSecurityToken Token, string, ProductRefNum )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
ProductRefNum string Unique gateway generated product id.

Response Parameters

Name Type Description
%Product% object Returns a Product object containing fields and their values.

Exceptions

Code Message Advice
41002 Product Not Found Product specified by ProductRefNum was not found. Make sure the number stored is not truncated or rounded.

Product Categories

addProductCategory

Example Request

    Dim category As usaepay.ProductCategory = New usaepay.ProductCategory
            category.Name = "The first"
            Dim response As String

            response = client.addProductCategory(token, category)
            MsgBox(response)

                usaepay.ProductCategory category = new usaepay.ProductCategory();
                category.Name = "The first";
                string response;

                try
                {
                    response = client.addProductCategory(token, category);
                    MessageBox.Show(string.Concat(response));
                }
                catch (Exception err)
                {
                    MessageBox.Show(err.Message);
                }

    <?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:addProductCategory>
    <Token xsi:type="ns1:ueSecurityToken">
    <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
    <PinHash xsi:type="ns1:ueHash">
    <HashValue xsi:type="xsd:string">e229fb6ce9c42bfc12c41f738dfc3984cb8a5461</HashValue>
    <Seed xsi:type="xsd:string">1975389982-test</Seed>
    <Type xsi:type="xsd:string">sha1</Type>
    </PinHash>
    <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
    </Token>
    <ProductCategory xsi:type="ns1:ProductCategory">
    <Name xsi:type="xsd:string">IceCream</Name>
    </ProductCategory>
    </ns1:addProductCategory>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Example Response

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

This method creates a new product category record and returns a ProductCategoryRefNum

The addProductCategory method creates a new product category record. If successful, a ProductCategoryRefNum will be returned. The ProductCategoryRefNum is a gateway assigned product category identifier. This product category identifier should be stored and is needed for updating and deleting product categories. The product database is an optional feature and may not be supported by all merchants. The merchant should check their gateway package to determine if this feature is available to them.

Related Methods

Syntax

string addProductCategory ( ueSecurityToken , ProductCategory )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
Name string Product Category name.

Response Parameters

Name Type Description
ProductCategoryRefNum string Unique gateway generated product category id.

Exceptions

Code Message Advice
41001 Unable to create product database Merchant does not have a product database. The feature not be enabled for merchant. Contact customer service and make sure product database feature is enabled.

deleteProductCategory

Example Request

            Dim catRefNum As String
            catRefNum = "9001169811"
            Dim response As Boolean

            response = client.deleteProductCategory(token, catRefNum)
            MsgBox(response)

                string catRefNum = "900116983";

                Boolean response;

                try
                {
                    response = client.deleteProductCategory(token, catRefNum);
                    MessageBox.Show(string.Concat(response));
                }
                catch (Exception err)
                {
                    MessageBox.Show(err.Message);
                }

This method deletes an existing product category.

This method removes the specified ProductCategoryRefNum from the product database. The product category is deleted immediately and this operation can not be undone. The ProductCategoryRefNum is the gateway assigned product Category ID that was returned by addProductCategory.

Related Methods

Syntax

boolean deleteProductCategory ( ueSecurityToken Token, string ProductCategoryRefNum )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
ProductCategoryRefNum string Product category reference number used to delete a product category.

Response Parameters

Name Type Description
deleteProductCategoryReturn boolean Returns true if product category has been deleted (on error an exception is thrown).

Exceptions

Code Message Advice
41008 Failed to delete product category Product category specified by ProductCategoryRefNum was not found. Make sure the number stored is not truncated or rounded.

getProductCategory

Example Request

        Dim catRefNum As String
            catRefNum = "9001169812"

            Dim category As usaepay.ProductCategory
            category = client.getProductCategory(token, catRefNum)
            MsgBox(category.Name)

                string catRefNum = "900116985";

                try
                {
                    usaepay.ProductCategory category = client.getProductCategory(token, catRefNum);
                    MessageBox.Show(string.Concat(category.Name));
                }
                catch (Exception err)
                {
                    MessageBox.Show(err.Message);
                }

Retrieve all data for a single product category

This method retrieves the ProductCategory object for the product category specified by ProductCateogryRefNum. The ProductCategoryRefNum is the gateway assigned unique product category identifier that was returned by addProductCategory.

The entire addProductCategory object is returned.

Related Methods

Syntax

addProductCategory getProductCategory ( ueSecurityToken Token, string ProductCategoryRefNum )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
ProductCategoryRefNum string Unique gateway generated product category id.

Response Parameters

Name Type Description
%ProductCategory% object Returns a Product Category object containing fields and their values.

Exceptions

Code Message Advice
41006 Product Category Not Found Product category specified by ProductCategoryRefNum was not found. Make sure the number stored is not truncated or rounded.

updateProductCategory

Example Request

    Dim catRefNum As String
            catRefNum = "9001169811"

            Dim category As usaepay.ProductCategory = New usaepay.ProductCategory
            category.Name = "third try"
            Dim response As Boolean

            response = client.updateProductCategory(token, catRefNum, category)
            MsgBox(response)

                string catRefNum = "900116983";

                usaepay.ProductCategory category = new usaepay.ProductCategory();
                category.Name = "next try";
                Boolean response;

                try
                {
                    response = client.updateProductCategory(token, catRefNum, category);
                    MessageBox.Show(string.Concat(response));
                }
                catch (Exception err)
                {
                    MessageBox.Show(err.Message);
                }

This method updates an existing product category.

Updates an existing product category based on its ProductCategoryRefNum. The entire product category is replaced by the contents of the Product category parameter. Developers can use the getProductCategory method to retrieve the Product category object, modify a field and then post the object back to the server.

Syntax

boolean updateProductCategory ( ueSecurityToken, ProductCategoryRefNum, ProductCategory )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
ProductCategoryRefNum string Unique gateway generated product category id.
%ProductCategory% object Returns a Product Category object containing fields and their values.

Response Parameters

Name Type Description
updateProductCategoryReturn boolean Returns a true if the product category is updated correctly.

Exceptions

Code Message Advice
41007 Error saving product category Product Category specified by ProductCategoryRefNum was not found. Make sure the number stored is not truncated or rounded.

getProductCategories

Example Request

            Dim category() As usaepay.ProductCategory
            category = client.getProductCategories(token)

            MsgBox(category.Length)

                try
                {
                    usaepay.ProductCategory[] category = client.getProductCategories(token);
                    MessageBox.Show(string.Concat(category.Length));
                }
                catch (Exception err)
                {
                    MessageBox.Show(err.Message);
                }

    <?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
     <ns1:getProductCategories>
    <Token xsi:type="ns1:ueSecurityToken">
    <ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
    <PinHash xsi:type="ns1:ueHash">
    <HashValue xsi:type="xsd:string">11ac55b0a0b59f8f028dbf85bc32266fa973dd0e</HashValue>
    <Seed xsi:type="xsd:string">12678150211876663375</Seed>
    <Type xsi:type="xsd:string">sha1</Type>
    </PinHash>
    <SourceKey xsi:type="xsd:string">HB4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
    </Token>
     </ns1:getProductCategories>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Example Response

    <?xml version="1.0" encoding="utf-8"?>
    <SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <SOAP-ENV:Body>
        <ns1:getProductCategoriesResponse>
          <getProductCategoriesReturn SOAP-ENC:arrayType="ns1:ProductCategory[4]" xsi:type="ns1:ProductCategoryArray">
            <item xsi:type="ns1:ProductCategory">
              <ProductCategoryRefNum xsi:type="xsd:string">900100191</ProductCategoryRefNum>
              <Name xsi:type="xsd:string">Books:Math</Name>
            </item>
            <item xsi:type="ns1:ProductCategory">
              <ProductCategoryRefNum xsi:type="xsd:string">900100193</ProductCategoryRefNum>
              <Name xsi:type="xsd:string">Example Category</Name>
            </item>
            <item xsi:type="ns1:ProductCategory">
              <ProductCategoryRefNum xsi:type="xsd:string">900100194</ProductCategoryRefNum>
              <Name xsi:type="xsd:string">Example Category</Name>
            </item>
            <item xsi:type="ns1:ProductCategory">
              <ProductCategoryRefNum xsi:type="xsd:string">900100192</ProductCategoryRefNum>
              <Name xsi:type="xsd:string">Test Category</Name>
            </item>
          </getProductCategoriesReturn>
        </ns1:getProductCategoriesResponse>
      </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Retrieve all product categories.

This method retrieves an array of ProductCategory objects for all product categories.

Related Methods

Syntax

ProductCategory getProductCategories ( ueSecurityToken

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.

Response Parameters

Name Type Description
%ProductCategory% array Returns an array of ProductCategory objects containing information on the product categories

Product Inventory

getProductInventory

Example Request

    <?php

    try {
      $ProductRefNum = '912093987473';
      $inventory = $client->getProductInventory($token, $ProductRefNum);

      print_r($inventory);
    }

    catch(SoapFault $e) {

      echo $e->getMessage();

    }

    ?>

    <?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope
      xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:ns1="urn:usaepay"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
      SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:getProductInventory>
      <Token xsi:type="ns1:ueSecurityToken">
        <ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
        <PinHash xsi:type="ns1:ueHash">
          <HashValue xsi:type="xsd:string">fa10e601d0c6be6c79fce2fdb89f51c65148f8bf</HashValue>
          <Seed xsi:type="xsd:string">12693612492090882854</Seed>
          <Type xsi:type="xsd:string">sha1</Type>
        </PinHash>
        <SourceKey xsi:type="xsd:string">1B93L5cpXV5hbx557d183q96EZ2jpqEf</SourceKey>
      </Token>
      <ProductRefNum xsi:type="xsd:string">9011780645</ProductRefNum>
    </ns1:getProductInventory>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Example Response

    <?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope
      xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:ns1="urn:usaepay"
      xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:getProductInventoryResponse>
      <getProductInventoryReturn SOAP-ENC:arrayType="ns1:ProductInventory[1]" xsi:type="ns1:ProductInventoryArray">
      <item xsi:type="ns1:ProductInventory">
        <InventoryLocation xsi:type="xsd:string">Los Angeles</InventoryLocation>
        <QtyOnHand xsi:type="xsd:string">5</QtyOnHand>
        <QtyOnOrder xsi:type="xsd:string">25</QtyOnOrder>
        <DateAvailable xsi:type="xsd:string">2009-10-10</DateAvailable>
      </item>
      </getProductInventoryReturn>
    </ns1:getProductInventoryResponse>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Retrieve all current inventory for a single product.

This method retrieves an array of ProductInventory objects for the product specified by ProductRefNum. The ProductRefNum is the gateway assigned unique product identifier that was returned by addProduct. searchProducts can be used to find the ProductRefNum for a product if it is not known.

Each element in the returned array represents the QtyOnHand and QtyOnOrder for each inventory location. For example, if you have inventory in three warehouses, an array with three elements will be returned.

Related Methods

Syntax

ProductInventory getProductInventory ( ueSecurityToken Token, string ProductRefNum)

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
ProductRefNum string Unique gateway generated product id.

Response Parameters

Name Type Description
%ProductInventory% array Returns an array of ProductInventory objects.

Exceptions

Code Message Advice
41002 Product Not Found Product specified by ProductRefNum was not found. Make sure the number stored is not truncated or rounded.

adjustInventory

Example Request

    Dim refNum As String
            refNum = "9001169811"

            Dim inventory(0 To 1) As usaepay.ProductInventory
            inventory(0) = New usaepay.ProductInventory()

            inventory(0).QtyOnHand = "+100"
            inventory(0).DateAvailable = "2010-08-12"

            Dim response() As usaepay.ProductInventory
            response = client.adjustInventory(token, refNum, inventory)
            MsgBox(response.Length)

                string RefNum = "900116985";

                usaepay.ProductInventory[] inventory = new usaepay.ProductInventory[1];
                inventory[0] = new usaepay.ProductInventory();

                inventory[0].QtyOnHand = "+100";
                inventory[0].DateAvailable = "2010-08-12";

                try
                {
                    usaepay.ProductInventory[] response = client.adjustInventory(token, RefNum, inventory);
                    MessageBox.Show(string.Concat(response.Length));
                }
                catch (Exception err)
                {
                    MessageBox.Show(err.Message);
                }

    <?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:adjustInventory>
    <Token xsi:type="ns1:ueSecurityToken">
    <ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
    <PinHash xsi:type="ns1:ueHash">
    <HashValue xsi:type="xsd:string">4e510e34e0e9a2ea067608e7a3298eeb453b3d0b</HashValue>
    <Seed xsi:type="xsd:string">11699233146-test</Seed>
    <Type xsi:type="xsd:string">sha1</Type>
    </PinHash>
    <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
    </Token>
    <ProductRefNum xsi:type="xsd:string">9001001994</ProductRefNum>
    <Inventory SOAP-ENC:arrayType="ns1:ProductInventory[1]" xsi:type="ns1:ProductInventoryArray">
    <item xsi:type="ns1:ProductInventory">
    <InventoryLocation xsi:type="xsd:string">La Mirada</InventoryLocation>
    <QtyOnHand xsi:type="xsd:string">50</QtyOnHand>
    <QtyOnOrder xsi:type="xsd:string">50</QtyOnOrder>
    <DateAvailable xsi:type="xsd:string">2016-01-01</DateAvailable>
    </item>
    </Inventory>
    </ns1:adjustInventory>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Example Response

    <?xml version="1.0" encoding="utf-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:adjustInventoryResponse>
    <adjustInventoryReturn SOAP-ENC:arrayType="ns1:ProductInventory[1]"
    xsi:type="ns1:ProductInventoryArray">
    <item xsi:type="ns1:ProductInventory">
    <InventoryLocation xsi:type="xsd:string">La Mirada</InventoryLocation>
    <QtyOnHand xsi:type="xsd:string">50</QtyOnHand>
    <QtyOnOrder xsi:type="xsd:string">50</QtyOnOrder>
    <DateAvailable xsi:type="xsd:string">2016-01-01</DateAvailable>
    </item>
    </adjustInventoryReturn>
    </ns1:adjustInventoryResponse>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

This method adjusts the inventory for a product.

This method can be used to either adjust or set the inventory for a product. The product to update inventory for is selected by the ProductRefNum parameter which is assigned by the gateway when the product was added. Inventory levels for multiple warehouses (inventory locations) may be set at the same time. The Inventory parameter is an array of ProductInventory objects containing the new qty levels or adjustments to current levels. Warehouses that are not sent in the array are left as is. Quantities sent as simple numbers will replace the existing quantities. If a "+" or "-" is sent before the number, the existing quantity will be either increased or decreased.

Starting Inventory

Inventory Location QtyOnHand QtyOnOrder
Los Angeles 5 200
Washington DC 10 0
New York 123 10
Chicago 24 0

Inventory Adjustment

Inventory Location QtyOnHand QtyOnOrder Date Available
Los Angeles +100 -100 8/10/2010
Washington DC 0 19 6/30/2010
New York -13 10 8/10/2010

Inventory After Adjustment

Inventory Location QtyOnHand QtyOnOrder Date Available
Los Angeles 105 100 8/10/2010
Washington DC 0 19 6/30/2010
New York 110 10 8/10/2010
Chicago 24 0

Related Methods

Syntax

ProductInventory adjustinventory ( ueSecurityToken ProductRefNum, ProductInventory)

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
ProductRefNum string Unique gateway generated product id.
%ProductInventory% array Array of ProductInventory objects containing qty or adjustments for each warehouse/inventory location.

Response Parameters

Name Type Description
%ProductInventory% array Returns an array of ProductInventory objects containing the adjusted inventory levels.

Exceptions

Code Message Advice
41002 Product Not Found Product specified by ProductRefNum was not found. Make sure the number stored is not truncated or rounded.
41003 Error Saving Product A database fault was encountered while saving product record. Try operation again or contact support.

Search Product Database

searchProducts

Example Request

    <?php

    try {

      // Create search parameter list
      $search=array(
        array(
          'Field'=>'name',   
          'Type'=>'eq',
          'Value'=>'A Great Product')
        );
      $start=0;
      $limit=100;
      $matchall=true;
      $sort='created';

      $res=$client->searchProducts($token,$search,$matchall,$start,$limit,$sort);

      print_r($res);

    }
    catch(SoapFault $e) {
      echo $client->__getLastResponse();
      die("Search Products Failed :".$e->getMessage());
    }

    ?>

    <?php

    include './nusoap.php';

    // Create Soap Client
    $s=new soapclient("./usaepay.wsdl",'wsdl');
    $tran=$s->getProxy();

    // Source Key Setting
    $sourcekey='yQbOFkjD8wwlkZ3AhY248k3Lc9PH1l14';
    $pin='1234';

    // Prep source key
    $seed=mktime() . rand();
    $tmp=$sourcekey . $seed . $pin;
    $hash=sha1($tmp);
    $token=array('SourceKey'=>$sourcekey, 'PinHash'=>array('Type'=>'sha1', 'Seed'=>$seed,'HashValue'=>$hash));


    // Prep Request data
    $search=array(
          array('Field'=>'title', 'Type'=>'eq','Value'=>'A Great Product')
    );
    $start=0;
    $limit=10;
    $matchall=true;
    $sort='created';

    $res=$tran->searchProducts($token,$search,$matchall,$start,$limit,$sort);

    if(!$err=$tran->getError()) {
            print_r($res);
    } else {

            echo "Error: $err\n";
            echo $tran->request;  

    }
        ?>

    Dim MatchAll As Boolean
            MatchAll = False
            Dim searchParams(1) As usaepay.SearchParam
            searchParams(0) = New usaepay.SearchParam
            searchParams(0).Field = "Created"
            searchParams(0).Type = "gt"
            searchParams(0).Value = "2010-09-07"

            Dim SearchResults As usaepay.ProductSearchResult = New usaepay.ProductSearchResult
            SearchResults = client.searchProducts(token, searchParams, MatchAll, "0", "1000", "created")

            MsgBox(SearchResults.ProductsMatched)

                usaepay.SearchParam[] param = new usaepay.SearchParam[1];
                param[0] = new usaepay.SearchParam();
                param[0].Field = "Created";
                param[0].Type = "Contains";
                param[0].Value = "2010-08-12";

                Boolean matchAll = true;
                string start = "0";
                string limit = "10";
                string sort = "created";

                usaepay.ProductSearchResult response = new usaepay.ProductSearchResult();

                try
                {
                    response = client.searchProducts(token, param, matchAll, start, limit, sort);
                    MessageBox.Show(string.Concat(response.ProductsMatched));
                }
                catch (Exception err)
                {
                    MessageBox.Show(err.Message);
                }

    <?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:searchTransactions>
    <Token xsi:type="ns1:ueSecurityToken">
    <ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
    <PinHash xsi:type="ns1:ueHash">
    <HashValue xsi:type="xsd:string">11ac55b0a0b59f8f028dbf85bc32266fa973dd0e</HashValue>
    <Seed xsi:type="xsd:string">12678150211876663375</Seed>
    <Type xsi:type="xsd:string">sha1</Type>
    </PinHash>
    <SourceKey xsi:type="xsd:string">HB4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
    </Token>
    <Search SOAP-ENC:arrayType="ns1:SearchParam[1]" xsi:type="ns1:SearchParamArray">
    <item xsi:type="ns1:SearchParam">
    <Field xsi:type="xsd:string">amount</Field>
    <Type xsi:type="xsd:string">eq</Type>
    <Value xsi:type="xsd:string">29.00</Value>
    </item>
    </Search>
    <MatchAll xsi:type="xsd:boolean">true</MatchAll>
    <Start xsi:type="xsd:integer">0</Start>
    <Limit xsi:type="xsd:integer">10</Limit>
    <Sort xsi:type="xsd:string">created</Sort>
    </ns1:searchTransactions>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Search products and return full product records.

The following fields may be used to search the database and return transaction details:

Related Methods

Syntax

ProductSearchResult searchProducts ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer limit, string sort)

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
%SearchParam% array Array of search parameters.
MatchAll boolean If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned.
Start integer Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200)
Limit integer Maximum number of records to return in result set.
Sort string Comma separated list of fields to sort by.

Response Parameters

Name Type Description
%ProductSearchResult% object Returns full product records for all products matching the specified search parameters.

searchProductsCount

Example Request

    Dim MatchAll As Boolean
            MatchAll = False
            Dim searchParams(1) As usaepay.SearchParam
            searchParams(0) = New usaepay.SearchParam
            searchParams(0).Field = "Created"
            searchParams(0).Type = "gt"
            searchParams(0).Value = "2010-09-07"

            Dim SearchResults As usaepay.ProductSearchResult = New usaepay.ProductSearchResult
            SearchResults = client.searchProductsCount(token, searchParams, MatchAll, 0, 1000, "created")

            MsgBox(SearchResults.ProductsMatched)

                usaepay.SearchParam[] param = new usaepay.SearchParam[1];
                param[0] = new usaepay.SearchParam();
                param[0].Field = "Created";
                param[0].Type = "Contains";
                param[0].Value = "2010-08-12";

                Boolean matchAll = true;
                string start = "0";
                string limit = "10";
                string sort = "created";

                usaepay.ProductSearchResult response = new usaepay.ProductSearchResult();

                try
                {
                    response = client.searchProductsCount(token, param, matchAll, start, limit, sort);
                    MessageBox.Show(string.Concat(response.ProductsMatched));
                }
                catch (Exception err)
                {
                    MessageBox.Show(err.Message);
                }

Search the product database, only return number of products matched.

Identical to the searchProducts method except only the product counts are returned. Like searchProducts, this method returns productsearchresult. The only difference is that ProductSearchResult.Products is left empty. This method provides a quicker way to determine the size of the result set before starting to retrieve the full search results.

Related Methods

Syntax

ProductSearchResult searchProductsCount ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string Sort )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
%SearchParam% array Array of search parameters.
MatchAll boolean If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned.
Start integer Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200)
Limit integer Maximum number of records to return in result set.
Sort string Comma separated list of fields to sort by.

Response Parameters

Name Type Description
%ProductSearchResult% object Returns full products records for all products matching the specified search parameters.

searchProductsCustom

Example Request

<?php

try {

  // Create search parameter list
  $search=array(
    array(
      'Field'=>'name',   
      'Type'=>'eq',
      'Value'=>'A Great Product')
    );
  $start=0;
  $limit=100;
  $matchall=true;
  $sort='created';

  $res=$client->searchProducts($token,$search,$matchall,$start,$limit,$sort);

  print_r($res);

}
catch(SoapFault $e) {
  echo $client->__getLastResponse();
  die("Search Products Failed :".$e->getMessage());
}

?>

    <?php

    include './nusoap.php';

    // Create Soap Client
    $s=new soapclient("./usaepay.wsdl",'wsdl');
    $tran=$s->getProxy();

    // Source Key Setting
    $sourcekey='yQbOFkjD8wwlkZ3AhY248k3Lc9PH1l14';
    $pin='1234';

    // Prep source key
    $seed=mktime() . rand();
    $tmp=$sourcekey . $seed . $pin;
    $hash=sha1($tmp);
    $token=array('SourceKey'=>$sourcekey, 'PinHash'=>array('Type'=>'sha1', 'Seed'=>$seed,'HashValue'=>$hash));


    // Prep Request data
    $search=array(
          array('Field'=>'title', 'Type'=>'eq','Value'=>'A Great Product')
    );
    $start=0;
    $limit=10;
    $matchall=true;
    $sort='created';

    $res=$tran->searchProducts($token,$search,$matchall,$start,$limit,$sort);

    if(!$err=$tran->getError()) {
            print_r($res);
    } else {

            echo "Error: $err\n";
            echo $tran->request;  

    }
        ?>

      Dim search(0 To 1) As usaepay.SearchParam
            search(0) = New usaepay.SearchParam()

            search(0).Field = "Created"
            search(0).Type = "Contains"
            search(0).Value = "2010-09-07"

            Dim matchAll As Boolean
            matchAll = True
            Dim start As String
            start = "0"
            Dim limit As String
            limit = "10"

            Dim FieldList(0 To 2) As String

            FieldList(0) = "ProductRefNum"
            FieldList(1) = "Name"
            FieldList(2) = "Price"

            Dim format As String
            format = "csv"
            Dim sort As String
            sort = "created"
            Dim result As String

            result = client.searchProductsCustom(token, search, matchAll, start, limit, FieldList, format, sort)
            Dim binaryData() As Byte
            binaryData = Convert.FromBase64String(result)

            MsgBox(Encoding.UTF8.GetString(binaryData))

                usaepay.SearchParam[] search = new usaepay.SearchParam[1];
                search[0] = new usaepay.SearchParam();

                search[0].Field = "Created";
                search[0].Type = "Contains";
                search[0].Value = "2010-08-12";

                Boolean matchAll = true;
                string start = "0";
                string limit = "10";

                string[] FieldList = new string[3];
                FieldList[0] = "ProductRefNum";
                FieldList[1] = "Name";
                FieldList[2] = "Price";

                string format = "csv";
                string sort = "created";

                string result;

                try
                {
                    result = client.searchProductsCustom(token, search, matchAll, start, limit, FieldList, format, sort);
                    Byte[] binaryData = new Byte[3];
                    binaryData = Convert.FromBase64String(result);

                    MessageBox.Show(Encoding.UTF8.GetString(binaryData));

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

    <?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:searchTransactions>
    <Token xsi:type="ns1:ueSecurityToken">
    <ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
    <PinHash xsi:type="ns1:ueHash">
    <HashValue xsi:type="xsd:string">34108e1b91894ab1da5ecdc213341c6d757217c1</HashValue>
    <Seed xsi:type="xsd:string">11936961311067412713</Seed>
    <Type xsi:type="xsd:string">sha1</Type>
    </PinHash>
    <SourceKey xsi:type="xsd:string">HB4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
    </Token>
    <Search SOAP-ENC:arrayType="ns1:SearchParam[1]" xsi:type="ns1:SearchParamArray">
    <item xsi:type="ns1:SearchParam">
    <Field xsi:type="xsd:string">amount</Field>
    <Type xsi:type="xsd:string">eq</Type>
    <Value xsi:type="xsd:string">29.00</Value>
    </item>
    </Search>
    <MatchAll xsi:type="xsd:boolean">true</MatchAll>
    <Start xsi:type="xsd:integer">0</Start>
    <Limit xsi:type="xsd:integer">10</Limit>
    <Sort xsi:type="xsd:string">created</Sort>
    </ns1:searchTransactions>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Search products and return specific fields in csv, tab or xml format.

Like searchProducts this function allows for the searching of the product database. Instead of return all data about each product in Product object form, it takes a FieldList parameter which specifies which fields should be returned. The results can be returned in a csv, tab or xml format. In all cases the data is base64 encoded. Developer must decode the data before using.

The following fields may be used to search the database and return transaction details:

Related Methods

Syntax

ProductSearchResult searchproducts ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string FieldList, string Format, string Sort )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
%SearchParam% array Array of search parameters.
MatchAll boolean If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned.
Start integer Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200)
Limit integer Maximum number of records to return in result set.
Sort string Comma separated list of fields to sort by.
FieldList list List of fields to return in search.
Format string Specify format of return data. Possible formats include: csv, tab, xml.

Response Parameters

Name Type Description
searchProductsCustomReturn string Base64 encode result set. Returns all of the fields from any transactions matching your search parameters.

Report Methods

Transaction Reports

getReport

Example Request

 <?php

    try {

      $Options = array(
        array('Field'=>'StartDate', 'Value'=>'2007/01/01'),
        array('Field'=>'EndDate', 'Value'=>'2007/04/01')
      );
      $Format='csv';
      $Report='CreditCard:Errors By Date';

      $res=$client->getReport($token, $Report, $Options, $Format);  
      $data=base64_decode($res);
      print_r($data);

    }

    catch (SoapFault $e) {
      die("Get Transaction failed :" .$e->getMessage());
      }

    ?>

Dim report As String
            report = "creditcard:errors by date"
            Dim options(0 To 1) As usaepay.FieldValue
            options(0) = New usaepay.FieldValue
            options(1) = New usaepay.FieldValue
            options(0).Field = "Start date"
            options(0).Value = "2010-08-01"
            options(1).Field = "End date"
            options(1).Value = "2010-08-16"

            Dim format As String
            format = "csv"
            Dim response As String

            response = client.getReport(token, report, options, format)
            Dim binary_data As Byte() = Convert.FromBase64String(response)


            MsgBox(System.Text.Encoding.UTF8.GetString(binary_data))

string report = "creditcard:errors by date ";

                usaepay.FieldValue[] options = new usaepay.FieldValue[2];
                for (int i = 0; i < 2; i++)
                {
                    options[i] = new usaepay.FieldValue();
                }

                options[0].Field = "StartDate"; options[0].Value = "2010-08-01";
                options[1].Field = "EndDate";   options[1].Value = "2010-08-16";

                string format = "csv";

                string response;

                try
                    {
                       response = client.getReport(token, report, options, format);
                       Byte[] binaryData = new Byte[3];
                       binaryData = Convert.FromBase64String(response);

                       MessageBox.Show(Encoding.UTF8.GetString(binaryData));

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

<?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:getReport>
    <Token xsi:type="ns1:ueSecurityToken">
    <ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
    <PinHash xsi:type="ns1:ueHash">
    <HashValue xsi:type="xsd:string">cb451c1c7cd0c9928933c074d6e4b239</HashValue>
    <Seed xsi:type="xsd:string">1234</Seed>
    <Type xsi:type="xsd:string">md5</Type>
    </PinHash>
    <SourceKey xsi:type="xsd:string">_0409i1S8XvmVj3ndoBG0HlBu32kYD3t</SourceKey>
    </Token>
    <Report xsi:type="xsd:string">creditcard:declines by user</Report>
    <Format xsi:type="xsd:string">csv</Format>
    <Options SOAP-ENC:arrayType="ns1:FieldValue[2]" xsi:type="ns1:FieldValueArray">
    <item xsi:type="ns1:FieldValue">
    <Field xsi:type="xsd:string">StartDate</Field>
    <Value xsi:type="xsd:string">2013/01/01</Value>
    </item>
    <item xsi:type="ns1:FieldValue">
    <Field xsi:type="xsd:string">EndDate</Field>
    <Value xsi:type="xsd:string">2013/12/12</Value>
    </item>
    </Options>
    </ns1:getReport>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

This method retrieves a report from the merchant console. Any reports, including custom reports, may be retrieved. The returned data is base 64 encoded. The format of the returned data can be HTML, comma separated (cvs), or tab separated (tab).

Names of built-in reports are prefaced with "CreditCard:", "Check:" or "Customer:". For example, to pull "Sales by Date" for credit cards, the "Report" parameter would be set to "CreditCard:Sales by Date."

To pull a custom credit card or check report, prefix the name with "Custom:" or "CustomCheck:" For example, to pull a custom report titled "Recurring Declines" set the "Report" parameter to "Custom:Recurring Declines." Customer reports can only be created from within the merchant console. If none of the built-in or custom reports provide data required, see the custom search methods (ie searchTransactionsCustom) for more flexibility.

Related Methods

Syntax

string getReport ( ueSecurityToken Token, string Report FieldValue Options, string Format )

Credit Card Reports

Available Reports Reports Description
creditcard:errors by date Credit card transactions resulting in errors, sorted by date
creditcard:errors by source Credit card transactions resulting in errors, sorted by source key
creditcard:errors by reason Credit card transactions resulting in errors, sorted by reason
creditcard:errors by user Credit card transactions resulting in errors, sorted by user
creditcard:declines by date Credit card transactions resulting in declines, sorted by date
creditcard:declines by source Credit card transactions resulting in declines, sorted by source key
creditcard:declines by reason Credit card transactions resulting in declines, sorted by reason
creditcard:declines by user Credit card transactions resulting in declines, sorted by user
creditcard:sales by date Credit card transactions resulting in approval, sorted by date
creditcard:sales by source Credit card transactions resulting in approval, sorted by source key
creditcard:sales by reason Credit card transactions resulting in approval, sorted by reason
creditcard:sales by user Credit card transactions resulting in approval, sorted by user

Check Reports

Available Reports Reports Description
check:Deposit Report Check transactions sorted by estimated deposit date
check:All Transactions by Date All Check transactions sorted by date (does not include errors)
check:settled by date Check transactions that have been marked as settled, sorted by date
check:settled by source Check transactions that have been marked as settled, sorted by source
check:settled by users Check transactions that have been marked as settled, sorted by user
check:returns by date Check transactions that have been marked as returned, sorted by date
check:returns by source Check transactions that have been marked as returned, sorted by source
check:returns by reason Check transactions that have been marked as returned, sorted by reason
check:returns by user Check transactions that have been marked as returned, sorted by user
check:declines by date Check transactions were rejected by check processor, sorted by date
check:declines by source Check transactions were rejected by check processor, sorted by sourcekey
check:declines by reason Check transactions were rejected by check processor, sorted by reason
check:declines by user Check transactions were rejected by check processor, sorted by user

Customer Reports

Available Reports Reports Description
customer:Pending Billing by Date Customers that are pending for recurring billing, sorted by next bill date
customer:Pending Billing by Source Customers that are pending for recurring billing, sorted by Source
customer:Billing History by Date Transactions results for recurring billing, sorted by billing date
customer:Billing History by Source Transactions results for recurring billing, sorted by Source
customer:Expired Cards Customers who have an expired credit card on file
customer:Expiring before Next Billing Customers that have a credit card that will expire before the next payment is scheduled to run
customer:Expiring by Date Range Customers that have a credit card expiring in the future

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
Options array Array of FieldValue objects specifying report options such as (StartDate and EndDate)
Report String Name of report to retrieve.
Format String Format of returned report data. Possible values are: html, csv, or tab.

Response Parameters

Name Type Description
getReportReturn string Returns specified report data according to parameters set in search.

Exceptions

Code Message Advice
20014 Unsupported file format Valid file formats are html, csv or tab.
20028 Requested Report not found Double check the name of the report.
20029 Unable to retrieve requested report An account configuration issue was encountered while generating the report. Contact support for assistance.

getTransactionReport

Example Request

<?php

    try {

      $StartDate='2007/01/01';
      $EndDate='2007/04/10';
      $Format='csv';
      $Report='CreditCard:Errors By Date';

      $res=$client->getTransactionReport($token, $StartDate, $EndDate, $Report, $Format);  
      $data=base64_decode($res);
      print_r($data);

    }

    catch (SoapFault $e) {
      die("Get Transaction failed :" .$e->getMessage());
      }

    ?>

try {
      String StartDate = "2009/01/01";
      String EndDate = "2009/09/09";
      String Format = "html";
      String Report = "CreditCard:Errors By Date";

      String response = client.getTransactionReport(token, StartDate, EndDate, Report, Format);

      BASE64Decoder decoder = new BASE64Decoder();
      byte[] decodedBytes = decoder.decodeBuffer(response);

      String report = new String(decodedBytes);
      System.out.println(report);
    } catch (Exception e) {
        System.out.println("Soap Exception: " + e.getMessage());
    }

Dim start As String
            start = "2010-08-01"
            Dim endd As String
            endd = "2010-08-09"
            Dim format As String
            format = "html"
            Dim report As String
            report = "CreditCard:Sales By Date"

            Dim response As String
            response = client.getTransactionReport(token, start, endd, report, format)
            Dim decbuff() As Byte
            decbuff = Convert.FromBase64String(response)
            MsgBox(Encoding.UTF8.GetString(decbuff))

string start = "2010-08-01";
                string end = "2010-08-09";
                string format = "html";
                string report = "CreditCard:Sales By Date";

                try
                {
                    string response = client.getTransactionReport(token, start, end, report, format);
                    byte[] decbuff = Convert.FromBase64String(response);
                    MessageBox.Show(Encoding.UTF8.GetString(decbuff));
                }

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

This method retrieves a report from the merchant console. Any reports, including custom reports, may be retrieved. The returned data is base 64 encoded. The format of the returned data can be HTML, comma separated (cvs), or tab separated (tab).

Names of built-in reports are prefaced with either "CreditCard:" or "Check:" For example, to pull "Sales by Date" for credit cards, the "Report" parameter would be set to "CreditCard:Sales by Date."

To pull a custom credit card or check report, prefix the name with "Custom:" or "CustomCheck:" For example, to pull a custom report titled "Recurring Declines" set the "Report" parameter to "Custom:Recurring Declines."

Related Methods

Syntax

string getTransactionReport ( ueSecurityToken Token, string StartDate, string EndDate, string Report, string Format )

Credit Card Reports

Available Reports Reports Description
creditcard:errors by date Credit card transactions resulting in errors, sorted by date
creditcard:errors by source Credit card transactions resulting in errors, sorted by source key
creditcard:errors by reason Credit card transactions resulting in errors, sorted by reason
creditcard:errors by user Credit card transactions resulting in errors, sorted by user
creditcard:declines by date Credit card transactions resulting in declines, sorted by date
creditcard:declines by source Credit card transactions resulting in declines, sorted by source key
creditcard:declines by reason Credit card transactions resulting in declines, sorted by reason
creditcard:declines by user Credit card transactions resulting in declines, sorted by user
creditcard:sales by date Credit card transactions resulting in approval, sorted by date
creditcard:sales by source Credit card transactions resulting in approval, sorted by source key
creditcard:sales by reason Credit card transactions resulting in approval, sorted by reason
creditcard:sales by user Credit card transactions resulting in approval, sorted by user

Check Reports

Available Reports Reports Description
check:Deposit Report Check transactions sorted by estimated deposit date
check:All Transactions by Date All Check transactions sorted by date (does not include errors)
check:settled by date Check transactions that have been marked as settled, sorted by date
check:settled by source Check transactions that have been marked as settled, sorted by source
check:settled by users Check transactions that have been marked as settled, sorted by user
check:returns by date Check transactions that have been marked as returned, sorted by date
check:returns by source Check transactions that have been marked as returned, sorted by source
check:returns by reason Check transactions that have been marked as returned, sorted by reason
check:returns by user Check transactions that have been marked as returned, sorted by user
check:declines by date Check transactions were rejected by check processor, sorted by date
check:declines by source Check transactions were rejected by check processor, sorted by sourcekey
check:declines by reason Check transactions were rejected by check processor, sorted by reason
check:declines by user Check transactions were rejected by check processor, sorted by user

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
StartDate string The earliest report date to retrieve.
EndDate string The latest report date to retrieve.
Report string Name of report to retrieve.
Format string Format of returned report data. Possible values are: html, csv, or tab.

Response Parameters

Name Type Description
getTransactionReportReturn string Returns specified report data according to parameters set in search.

Customer Reporting

getCustomerReport

This method retrieves a report from the merchant console. Any reports, including custom reports, may be retrieved. The returned data is base 64 encoded. The format of the returned data can be HTML, comma separated (cvs), or tab separated (tab).

Names of built-in reports are prefaced with "CreditCard:", "Check:" or "Customer:". For example, to pull "Sales by Date" for credit cards, the "Report" parameter would be set to "CreditCard:Sales by Date."

To pull a custom credit card or check report, prefix the name with "Custom:" or "CustomCheck:" For example, to pull a custom report titled "Recurring Declines" set the "Report" parameter to "Custom:Recurring Declines." Customer reports can only be created from within the merchant console. If none of the built-in or custom reports provide data required, see the custom search methods (ie searchTransactionsCustom) for more flexibility.

Available Reports Reports Description
customer:Pending Billing by Date Customers that are pending for recurring billing, sorted by next bill date
customer:Pending Billing by Source Customers that are pending for recurring billing, sorted by Source
customer:Future Billing by Date Customers that have recurring billing enabled, sorted by bill date
customer:Future Billing by Source Customers that have recurring billing enabled, sorted by source
customer:Billing History by Date Transactions results for recurring billing, sorted by billing date
customer:Billing History by Source Transactions results for recurring billing, sorted by Source
customer:Expired Cards Customers who have an expired credit card on file
customer:Expiring before Next Billing Customers that have a credit card that will expire before the next payment is scheduled to run
customer:Expiring by Date Range Customers that have a credit card expiring in the future

Related Methods

Syntax

string getCustomerReport ( ueSecurityToken Token, string Report, FieldValue Options, string Format )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
Options array Array of FieldValue objects specifying report options such as (StartDate and EndDate)
Report string Name of report to retrieve.
Format string Format of returned report data. Possible values are: html, csv, or tab.

Response Parameters

Name Type Description
getCustomerReportReturn string Returns specified report data according to parameters set in search.

Change Log

Version Description
1.3 Method added in this release

Settings Methods

Fraud Profiling

getSession

Example Request

<?php

    try {


      $res=$client->getSession($token);  
      print_r($data);

    }

    catch (SoapFault $e) {
      die("Get Session failed :" .$e->getMessage());
      }

    ?>

Dim response As usaepay.TransactionSession

    response = client.getSession(token, report, options, format)
    Dim binary_data As Byte() = Convert.FromBase64String(response)

    MsgBox("SessionID: " & response.SessionID);

usaepay.TransactionSession response;

    try
        {
           response = client.getSession(token);

           MessageBox.Show(response.SessionID);

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

This method generates a fraud profiling session. Fraud profiling allows merchants to perform in depth analysis and business risk assessment using third party services such as Threat Metrix. These premium services must be enabled on the merchants account before this method may be used.

The method returns a TransactionSession object which contains a session id and an org id. These variables are used to assemble the profiling html snippet that needs to be displayed to the end user. The session id is then passed in with the runTransaction, runSale, etc call.

See also: ThreatMetrix

Syntax

TransactionSession getSession ( ueSecurityToken Token )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.

Response Parameters

Name Type Description
%TransactionSession% object Returns session data.

Exceptions

Code Message Advice
20035 Merchant does not have fraud profiling enabled The merchant's account must be configured for fraud profiling. They should contact their reseller to sign up for the service.

getTransactionProfile

Example Request

<?php

    try {
      $RefNum='12345678';
      $data=$client->getTransactionProfile($token, $RefNum);  
      print_r($data);              
    }

    catch (SoapFault $e) {
      die("Call failed :" .$e->getMessage());
      }

    ?>

Dim response As usaepay.TransactionProfile

    response = client.getTransactionProfile(token, 1234567)

    MsgBox("DeviceID: " & response.DeviceID);

usaepay.TransactionProfile response;

    try
        {
           response = client.getTransactionProfile(token);

           MessageBox.Show(response.DeviceID);

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

This method retrieves the fraud profiling data for a given transaction.

Fraud profiling allows merchants to perform in depth analysis and business risk assessment using third party services such as Threat Metrix. These premium services must be enabled on the merchants account before this method may be used.

If profiling data is available, a TransactionProfile object is returned. This object contains profile data such as the scoring and extended device data.

See also: ThreatMetrix

Related Methods

Syntax

TransactionProfile getTransactionProfile ( ueSecurityToken Token, string RefNum )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
RefNum string Unique transaction reference number assigned by the gateway. You can also use TransKey in the RefNum field.

Response Parameters

Name Type Description
TransactionProfile string Returns fraud profile data.

Exceptions

Code Message Advice
20001 Specified transactions was not found RefNum didn't match any of the merchants transactions.
20035 Merchant does not have fraud profiling enabled The merchant's account must be configured for fraud profiling. They should contact their reseller to sign up for the service.

Change Log

Version Description
1.7 TransKey can be used in RefNum field.

Multi-Currency

getSupportedCurrencies

Example Request

<?php

    try {

      $currencies = $client->getSupportedCurrencies($token);
      print_r($currencies);                             
      }

    catch(SoapFault $e) {
      die("soap fault: " .$e->getMessage(). "\n\nRequest: " .   
      $this->client->__getLastResponse());         
    }

    ?>     

//PHP Pear SOAP
<?php

    $params=array("Token"=>$token);

    $currencies=$client->call('getSupportedCurrencies', $params);

    print_r($currencies);

    ?>

Dim response() As usaepay.CurrencyObject


            response = client.getSupportedCurrencies(token)
            MsgBox(response.Length)

try
                {
                    usaepay.CurrencyObject[] currency = client.getSupportedCurrencies(token);
                    MessageBox.Show(string.Concat(currency.Length));
                }

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

Depending on the merchant account configuration, different currencies are available for multi-currency processing. This method will return an array containing the currencies that are supported by the merchant account.

If multi-currency processing is not supported, the array will be empty.

To view the account details for a particular merchant account, including whether or not the account supports multi-currency processing, use the getAccountDetails method.

Each currency type is assigned a three digit numeric code (ie: USD=840, Japanese yen=392). You must enter the three digit code for both the original currency and the converted currency in a conversion. The Currency Code list provides all of the three digit codes and their corresponding currencies for international currency conversion.

If you would like to add support for multi-currency transactions to a merchant account please contact the merchant's service provider or customer service.

Related Methods

Syntax

CurrencyObject getSupportedCurrencies ( ueSecurityToken Token)

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.

Response Parameters

Name Type Description
%CurrencyObject% object Returns an array of currencies supported by the merchant account for use with multi-currency processing.

currencyConversion

Example Request

<?php

    // for directions on how to set up the
    // WSDL link and create "$mctoken" and "$client,"

    try {

       $ToCurrency='978';
       $FromCurrency='840';
       $Amount=50;    

       $res=$client->currencyConversion($mctoken, $FromCurrency, $ToCurrency, $Amount);
              print_r($res);

       $this->assertEquals($res->FromCurrency, $FromCurrency);

       $this->assertEquals($res->Currency, $ToCurrency);

       $this->assertTrue($res->Rate > 0);

       $this->assertTrue($res->Amount > 0);

    } catch (SoapFault $e) {
         echo $client->__getLastRequest();
         echo $client->__getLastResponse();
         die('Currency conversion failed : '.$e->getMessage());
    }

    ?>

Dim from As String
            Dim convert As String
            Dim amount As Double
            from = "036"
            convert = "826"
            amount = 50

            Dim response As usaepay.CurrencyConversion = New usaepay.CurrencyConversion

            response = client.currencyConversion(token, from, convert, amount)
            MsgBox(response.Amount)

string from = "840";
                string to = "978";
                int amount = 50;

                usaepay.CurrencyConversion response = new usaepay.CurrencyConversion();

                try
                {
                    response = client.currencyConversion(token, from, to, amount);
                    MessageBox.Show(string.Concat(response.Amount));
                }

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

This method allows you to determine the rate of conversion for different currencies in multi-currency transactions. A merchant account must have support for specific types of currency before it will be able to run multi-currency transactions.

To determine if a currency is supported by a merchant account, use either the getSupportedCurrencies or the getAccountDetails method.

Each currency type is assigned a three digit numeric code (ie: USD=840, Japanese yen=392). You must enter the three digit code for both the original currency and the converted currency in a conversion. The Currency Code list provides all of the three digit codes and their corresponding currencies for international currency conversion.

If you would like to add support for multi-currency transactions to a merchant account please contact the merchant's service provider or customer service.

Related Methods

Syntax

currencyConversion currencyConversion ( ueSecurityToken Token, integer FromCurrency, integer ToCurrency, double Amount )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
Amount double Amount of currency to be converted.
FromCurrency string Currency code funds will be converted from.
ToCurrency string Currency code funds will be converted to.

Response Parameters

Name Type Description
%CurrencyConversion% object Returns the rate of conversion and the amount of the converted currency.

bulkCurrencyConversion

Example Request

<?php

    try {

      $ToCurrency='978';
      $FromCurrency='840';
      $Amounts=array(
        50.10,
        11.23,
        34.21,
        12.23
        );     

      $res=$client->bulkCurrencyConversion($mctoken, $FromCurrency, $ToCurrency, $Amounts);
      print_r($res);

      $this->assertEquals(count($res), count($Amounts));

      $this->assertEquals($res[0]->FromCurrency, $FromCurrency);

      $this->assertEquals($res[0]->Currency, $ToCurrency);

      $this->assertEquals($res[0]->FromAmount, $Amounts[0]);

      $this->assertTrue($res[0]->Rate > 0);

      $this->assertTrue($res[0]->Amount > 0);

      }

    catch (SoapFault $e) {
      die('Currency conversion failed : '.$e->getMessage());
    }

    ?>

Dim from As String
            Dim convert As String
            Dim amount(0 To 2) As Double
            from = "036"
            convert = "826"
            amount(0) = 10
            amount(1) = 20
            amount(2) = 30

            Dim response() As usaepay.CurrencyConversion

            response = client.bulkCurrencyConversion(token, from, convert, amount)
            MsgBox(response.Length)

string from = "124";
                string to = "826";
                double[] amount = new double[3];
                amount[0] = 10;
                amount[1] = 5;
                amount[2] = 19.99;

                //usaepay.CurrencyConversion response = new usaepay.CurrencyConversion();

                try
                {
                    usaepay.CurrencyConversion[] response = client.bulkCurrencyConversion(token, from, to, amount);
                    MessageBox.Show(string.Concat(response.Length));
                }

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

This method allows you to complete a large batch of currency conversions all at once without having to use the CurrencyConversion method for each conversion.

Currently this method supports bulk conversions from a single currency to another single currency and not several currencies simultaneously. (ie: if you want to convert fifty amounts from USD [US dollars] to CAD [Canadian dollars] and twenty amounts from USD to EUR [Euros] you would need to run two separate bulkCurrencyConversion method calls.)

To determine if a currency is supported by a merchant account, use either the getSupportedCurrencies or the getAccountDetails method.

Each currency type is assigned a three digit numeric code (ie: USD=840, Japanese yen=392). You must enter the three digit code for both the original currency and the converted currency in a conversion. The Currency Code list provides all of the three digit codes and their corresponding currencies for international currency conversion.

If you would like to add support for multi-currency transactions to a merchant account please contact the merchant's service provider or customer service.

Related Methods

Syntax

CurrencyConversion bulkCurrencyConversion ( ueSecurityToken Token, integer FromCurrency, integer ToCurrency, double Amounts )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
Amount double Amount of currency to be converted.
FromCurrency string Currency code funds will be converted from.
ToCurrency string Currency code funds will be converted to.

Response Parameters

Name Type Description
%CurrencyConversion% object Returns the rate of conversion and the amount of the converted currency.

Account Details/System Info

getAccountDetails

Example Request

<?php

    try {

      $details = $client->getAccountDetails($token);

    }

    catch(SoapFault $e) {

      echo "soap fault: " .$e->getMessage();

    }         

    ?>

try {
      AccountDetails Account = new AccountDetails();
      Account = client.getAccountDetails(token);
    } catch (Exception e) {
        System.out.println("Soap Exception: " + e.getMessage());
    }

Dim response As usaepay.AccountDetails = New usaepay.AccountDetails
            response = client.getAccountDetails(token)
            MsgBox(response.CreditCardPlatform)

usaepay.AccountDetails merchant = new usaepay.AccountDetails();

                try
                {
                    merchant = client.getAccountDetails(token);
                    MessageBox.Show(string.Concat(merchant.CreditCardPlatform));
                }

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

<?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:getAccountDetails>
    <Token xsi:type="ns1:ueSecurityToken">
    <ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
    <PinHash xsi:type="ns1:ueHash">
    <HashValue xsi:type="xsd:string">11ac55b0a0b59f8f028dbf85bc32266fa973dd0e</HashValue>
    <Seed xsi:type="xsd:string">12678150211876663375</Seed>
    <Type xsi:type="xsd:string">sha1</Type>
    </PinHash>
    <SourceKey xsi:type="xsd:string">HB4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
    </Token>
    </ns1:getAccountDetails>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

This method will return details about your merchant account. It is useful for determining what functionality your account supports.

For example this method can help you determine if your account includes support for check processing, multiple currencies or cardholder authentication.

Related Methods

Syntax

AccountDetails getAccountDetails ( ueSecurityToken Token )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.

Response Parameters

Name Type Description
%AccountDetails% object Returns details pertaining to the merchant account requested, including the name of their credit card platform, the merchant's type of industry, whether the merchant account supports check processing, type of cardholder authentication and an array of currencies supported by the account.

getSystemInfo

Example Request

    <?php
try {

    $response=$client->getSystemInfo($this->token);
    print_r($response);
}

catch (SoapFault $e){
    echo $client->__getLastRequest();
    echo $client->__getLastResponse();
    $this->fail("Get SystemInfo failed:" .$e->getMessage());
}
    ?>

Dim info As usaepay.SystemInfo = New usaepay.SystemInfo
            info = client.getSystemInfo(token)
            MsgBox(info.ApiVersion)

try
                {
                    usaepay.SystemInfo system = client.getSystemInfo(token);
                    MessageBox.Show(string.Concat(system.ApiVersion));

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

This method pulls the system information.

Information accessible through this method includes API version number, environment (production/sandbox/staging), data-center location, and the current time.

Syntax

SystemInfo getSystemInfo ( ueSecurityToken Token )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.

Response Parameters

Name Type Description
%SystemInfo% object Retrieves API version, environment, data-center, time.

getSyncLog

Example Request

Dim ObjectName As String
            ObjectName = "Product"
            Dim FromPosition As String

            Dim log() As usaepay.SyncLog
            log = client.getSyncLog(token, ObjectName, FromPosition)
            MsgBox(log.Length)    

string ObjectName = "Product";
                string FromPosition = "0";

                try
                {
                    usaepay.SyncLog[] log = client.getSyncLog(token, ObjectName, FromPosition);
                    MessageBox.Show(string.Concat(log.Length));

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

 <?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:usaepay" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
     <SOAP-ENV:Body>
      <ns1:getSyncLog>
       <Token xsi:type="ns1:ueSecurityToken">
    <ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
    <PinHash xsi:type="ns1:ueHash">
    <HashValue xsi:type="xsd:string">11ac55b0a0b59f8f028dbf85bc32266fa973dd0e</HashValue>
    <Seed xsi:type="xsd:string">12678150211876663375</Seed>
    <Type xsi:type="xsd:string">sha1</Type>
    </PinHash>
    <SourceKey xsi:type="xsd:string">HB4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
    </Token>
       <ObjectName xsi:type="xsd:string">
        Product
       </ObjectName>
       <FromPosition xsi:type="xsd:integer">
        181
       </FromPosition>
      </ns1:getSyncLog>
     </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Example Response

<?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
     xmlns:ns1="urn:usaepay" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
     <SOAP-ENV:Body>
      <ns1:getSyncLogResponse>
       <getSyncLogReturn SOAP-ENC:arrayType="ns1:SyncLog[1]" xsi:type="ns1:SyncLogArray">
        <item xsi:type="ns1:SyncLog">
         <SyncPosition xsi:type="xsd:integer">
          181
         </SyncPosition>
         <ObjectName xsi:type="xsd:string">
          Product
         </ObjectName>
         <RefNum xsi:type="xsd:string">
          9011780645
         </RefNum>
         <ChangeDate xsi:type="xsd:dateTime">
          2010-03-23T09:01:40
         </ChangeDate>
         <Action xsi:type="xsd:string">
          Update
         </Action>
        </item>
       </getSyncLogReturn>
      </ns1:getSyncLogResponse>
     </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

This method allows for the intelligent synchronization of data between the gateway and the developer's software.

Related Methods

Syntax

SyncLog getSyncLog ( ueSecurityToken ObjectName, FromPosition )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
ObjectName string The name of object being synced (leave blank to look at all objects).c
FromPosition integer Specifies the log position to start from.

Response Parameters

Name Type Description
%SyncLog% object Returns as array of SyncLog objects.

Exceptions

Code Message Advice
41004 Unknown Object The specified ObjectName was not recognized. ObjectName must either be left blank (for all objects) or must correspond to a valid object (ie Product, Customer, etc).

getSyncLogCurrentPosition

Example Request

Dim ObjectName As String
            ObjectName = "Product"

            Dim log As String
            log = client.getSyncLogCurrentPosition(token, ObjectName)
            MsgBox(log)

string ObjectName = "Product";
                string response;

                try
                {
                    response = client.getSyncLogCurrentPosition(token, ObjectName);
                    MessageBox.Show(string.Concat(response));

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

The system keeps a log of every change made to various objects (such as Product, Customers, etc). Each change is tagged with a sequential log position (starting at 1 and counting up). This method returns the last position in the log for the given ObjectName. This is useful if you have just retrieved all products from the server and are now ready to start doing incremental syncing. (See the getSyncLog method for more information on incremental syncing).

Leave ObjectName blank to retrieve the last position for all objects.

Syntax

integer getSyncLogCurrentPosition ( ueSecurityToken ObjectName )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.
ObjectName string Type of object: Product, Customer, etc.

Response Parameters

Name Type Description
getSyncLogCurrentPositionReturn integer Returns the current sync position for ObjectName

Exceptions

Code Message Advice
41004 Unknown Object The specified ObjectName was not recognized. ObjectName must either be left blank (for all objects) or must correspond to a valid object (ie Product, Customer, etc).

getCustomFields

Example Request

<?php

    try {

      $res = $client->getCustomFields($token);
      print_r($res);
    }

    catch(SoapFault $e) {

      echo $e->getMessage();

    }

    ?>

Dim trace() As usaepay.FieldValue

            trace = client.getCustomFields(token)
            MsgBox(trace(0).Value)

try
                {
                    usaepay.FieldValue[] response = client.getCustomFields(token);
                    MessageBox.Show(string.Concat(response.Length));

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

<?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope
      xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:ns1="urn:usaepay" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
      SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:getCustomFields>
     <Token xsi:type="ns1:ueSecurityToken">
    <ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
    <PinHash xsi:type="ns1:ueHash">
    <HashValue xsi:type="xsd:string">11ac55b0a0b59f8f028dbf85bc32266fa973dd0e</HashValue>
    <Seed xsi:type="xsd:string">12678150211876663375</Seed>
    <Type xsi:type="xsd:string">sha1</Type>
    </PinHash>
    <SourceKey xsi:type="xsd:string">HB4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
    </Token>
    </ns1:getCustomFields>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Example Response

<?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope
      xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:ns1="urn:usaepay"
      xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:getCustomFieldsResponse>
    <getCustomFieldsReturn SOAP-ENC:arrayType="ns1:FieldValue[3]" xsi:type="ns1:FieldValueArray">
      <item xsi:type="ns1:FieldValue">
        <Field xsi:type="xsd:string">custom1</Field>
        <Value xsi:type="xsd:string">Favorite Color</Value>
      </item>
      <item xsi:type="ns1:FieldValue">
        <Field xsi:type="xsd:string">custom2</Field>
        <Value xsi:type="xsd:string">Favorite Movie</Value>
      </item>
      <item xsi:type="ns1:FieldValue">
        <Field xsi:type="xsd:string">custom3</Field>
        <Value xsi:type="xsd:string">Favorite Icecream</Value>
      </item>
    </getCustomFieldsReturn>
    </ns1:getCustomFieldsResponse>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

This method allows you to retrieve the custom fields for a specific gateway account.

Use this method to identify which custom fields exist.

To retrieve the list of custom fields a token must me provided as an argument. The token will be used to identify the specific gateway account.

Related Methods

Syntax

FieldValue getCustomFields ( ueSecurityToken )

Examples

Request Parameters

Name Type Description
%ueSecurityToken% object Merchant security token: used to identify merchant and validate transaction.

Response Parameters

Name Type Description
FieldValue array Returns a FieldValue array containing the custom field and its name.

Exceptions

Code Message Advice
40470 No custom fields defined. Merchant has not configured any custom fields. They must log into the merchant console to configure custom fields.

Objects

ueSecurityToken

Defines a source key used to identify a merchant or reseller.

This object defines a source key which is used to identify the merchant or reseller making the request. Source keys are obtained by logging into the merchant or reseller console.

A source key that has a pin assigned must include the Hash object. It is highly recommended that a pin always be used in conjunction with the source key.

All SOAP methods require the use of a pin, except the following transaction methods:

The ClientIP is used to reference the end client. While this field is not required (it can be left blank) it is used by several fraud modules and is recommended.

Properties

Example Code

    <?php
    class TokenClientExample {

        public $client; // initialize client
        public $token;// initialize token

        function setUp{
            $client=self::getClient(); //Using this class
            $token=self::getToken();   //Using this class
        }

        static function getClient(){
            //for live server use 'www' for test server use 'sandbox'
            $wsdl='https://www.usaepay.com/soap/gate/131C979E/usaepay.wsdl';

            return new SoapClient($wsdl,array("trace"=>1,"exceptions"=>1));
            //Must have Php5 compiled with --enable-soap
            *Otherwise use pear soap. For more info please visit: http:*pear.php.net/package/SOAP
        }

        static function getToken(){
            // Creating a ueSecurityToken

            $sourcekey = 'yQbOFkmykeygoeshere3Lc9PH1l14';
    //Input your merchant console generated source key
            $pin = '1234'; //Input the PIN set in the source editor for your source key

            // generate random seed value
            $seed=mktime() . rand();

            // make hash value using sha1 function
            $clear= $sourcekey . $seed . $pin;
            $hash=sha1($clear);

            // assembly ueSecurityToken as an array
            // (php5 will correct the type for us)
            $tok=array(
             'SourceKey'=>$sourcekey,
             'PinHash'=>array(
                'Type'=>'sha1',
                'Seed'=>$seed,
                'HashValue'=>$hash
                ),
             'ClientIP'=>'192.168.0.1'
            );
            return $tok;
        }
    }
        ?>

    <?php
    // Creating a ueSecurityToken
    $sourcekey = 'yQbOFkjD8wwlkZ3AhY248k3Lc9PH1l14';
    $pin = '1234';

    // generate random seed value
    $seed=mktime() . rand();

    // make hash value using sha1 function
    $clear= $sourcekey . $seed . $pin;
    $hash=sha1($clear);

    // assembly ueSecurityToken as an array
    // (php4 will correct the type for us)
    $token=array(
     'SourceKey'=>$sourcekey,
     'PinHash'=>array(
            'Type'=>'sha1',
            'Seed'=>$seed,
            'HashValue'=>$hash
            ),
     'ClientIP'=>'192.168.0.1'
    );
        ?>

    Imports System
    Imports System.Web
    Imports System.IO
    Imports System.Security.Cryptography
    Imports System.Text

    Private Sub mySoapCall()

      Dim token As usaepay.ueSecurityToken
      Dim hash As usaepay.ueHash = New usaepay.ueHash
      Dim sourcekey As String
      Dim pin As String

      ' The source key and pin are created by the merchant
      sourcekey = "e42SYc86C4uvlvyP62ow54Kv93SZsJVm"
      pin = "1234"

      token = New usaepay.ueSecurityToken
      token.SourceKey = sourcekey

      ' To create the hash we must concat the sourcekey, seed and pin
      Dim rand As System.Random = New System.Random
      hash.Seed = Date.Now.ToUniversalTime & rand.Next()

      Dim prehashvalue As String
      prehashvalue = sourcekey & hash.Seed & pin

      ' Generate the md5 hash
      hash.Type = "md5"
      hash.HashValue = GenerateHash(prehashvalue)
      token.PinHash = hash

    End Sub


    Private Function GenerateHash(ByVal SourceText As String) As String
      'Instantiate an MD5 Provider object
      Dim md5 As New MD5CryptoServiceProvider

      'Compute the hash value from the source
      Dim ByteHash() As Byte = md5.ComputeHash(Encoding.Default.GetBytes(SourceText))

      'Instantiate a StringBuilder object
      Dim sb As New StringBuilder

      'Repack binary hash as hex
      For c As string = 0 To ByteHash.Length - 1
        sb.AppendFormat("{0:x2}", ByteHash(c))
      Next c

      'Return the hex hash
      Return sb.ToString
    End Function

    usaepay.ueSecurityToken token = new usaepay.ueSecurityToken();

                // SourceKey and Pin (created in merchant console)
                token.SourceKey = "O79****************************c8";

                string pin = "1234";

                // IP address of end user (if applicable)
                token.ClientIP = "11.22.33.44";  

                // Instantiate Hash
                usaepay.ueHash hash = new usaepay.ueHash();
                hash.Type = "md5";  // Type of encryption
                hash.Seed = Guid.NewGuid().ToString();  // unique encryption seed

                // Assemble string and hash
                string prehashvalue = string.Concat(token.SourceKey, hash.Seed, pin);
                hash.HashValue = GenerateHash(prehashvalue);

                // Add hash to token
                token.PinHash = hash;

Name Type Description
SourceKey string SourceKey obtained in merchant console.
%ueHash% PinHash Hash object for the PIN (only necessary if this source key has a pin assigned)
ClientIP string The IP Address of the end client

ueHash

Defines the properties of the hash used to validate a source key.

This object defines the properties of the hash used to validate a source key. This object is only required on source keys that have a pin assigned.

Pins are not meant to be stored by the application. Instead the application should prompt the end user for the pin. The pin may be cached temporarily, but should not be stored permanently unless appropriate security measures such as strong encryption are taken.

Please note that access to certain methods will require a pin. These features are restricted to sources with a pin to minimize the impact of a merchant's source key being stolen.

Properties

Example Code

    Dim hash As usaepay.ueHash = New usaepay.ueHash
    Dim sourcekey As String
      Dim pin As String

      ' The source key and pin are created by the merchant
      sourcekey = "e42SYc86C4uvlvyP62ow54Kv93SZsJVm"
      pin = "1234"

      token = New usaepay.ueSecurityToken
      token.SourceKey = sourcekey

      ' To create the hash we must concat the sourcekey, seed and pin
      Dim rand As System.Random = New System.Random
      hash.Seed = Date.Now.ToUniversalTime & rand.Next()

      Dim prehashvalue As String
      prehashvalue = sourcekey & hash.Seed & pin

      ' Generate the md5 hash
      hash.Type = "md5"
      hash.HashValue = GenerateHash(prehashvalue)
      token.PinHash = hash

    Private Function GenerateHash(ByVal SourceText As String) As String
      'Instantiate an MD5 Provider object
      Dim md5 As New MD5CryptoServiceProvider

      'Compute the hash value from the source
      Dim ByteHash() As Byte = md5.ComputeHash(Encoding.Default.GetBytes(SourceText))

      'Instantiate a StringBuilder object
      Dim sb As New StringBuilder

      'Repack binary hash as hex
      For c As Integer = 0 To ByteHash.Length - 1
        sb.AppendFormat("{0:x2}", ByteHash(c))
      Next c

      'Return the hex hash
      Return sb.ToString
    End Function

    MD5 md5Hasher = MD5.Create();

    // Convert the input string to a byte array and compute the hash.
    byte[] data = md5Hasher.ComputeHash(Encoding.Default.GetBytes(input));

    // Create a new Stringbuilder to collect the bytes
    // and create a string.
    StringBuilder sBuilder = new StringBuilder();

    // Loop through each byte of the hashed data
    // and format each one as a hexadecimal string.
    for (int i = 0; i < data.Length; i++)
    {
        sBuilder.Append(data[i].ToString("x2"));
    }

    // Return the hexadecimal string.
    return sBuilder.ToString();

Name Type Description
Type string Hashing Function Used: Currently only "md5" and "sha1" are supported.
Seed string The data used to seed the hash: This value must be unique and cannot be reused. The system will reject the request if a Seed is reused. The reason for this is to minimize the damage if a HashValue is stolen. An intruder may manage to obtain a SourceKey and a HashValue, but will not be able to use the source key since the HashValue is based on a seed that cannot be reused.
HashValue string Hash string: The resulting hash. The hash is calculated by concatenating the SourceKey, the Seed and the Pin value. Do not place any characters in between these values. Once the values have been concatenated, calculate the hash string using the algorithm specified by Type.

AccountDetails

Contains all relevant data pertaining to a merchant account.

This object details the functionality of a merchant account including type of processing platform, account industry, check processing capabilities, integrated cardholder authentication systems and types of currencies accepted by the merchant account.

Places Used

Properties

Example Object

    <?php
    // for directions on how to set up the  
    // WSDL link and create "$token" and "$client,"
    // see: [https://help.usaepay.info/developer/soap-api/howto/php/](https://help.usaepay.info/developer/soap-api/howto/php/)

       $AccountDetails = $this->client->getAccountDetails($this->token);

       echo $AccountDetails->CreditCardPlatform;
    ?>

    Dim response As usaepay.AccountDetails = New usaepay.AccountDetails
            response = client.getAccountDetails(token)
            MsgBox(response.CreditCardPlatform)

    usaepay.AccountDetails merchant = new usaepay.AccountDetails();

    try
    {
        merchant = client.getAccountDetails(token);
        MessageBox.Show(string.Concat(merchant.CreditCardPlatform));
    }

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

    <getAccountDetailsReturn xsi:type="ns1:AccountDetails">
    <CardholderAuthentication xsi:type="xsd:string">Disabled</CardholderAuthentication>
    <CheckPlatform xsi:type="xsd:string">TestBed</CheckPlatform>
    <CreditCardPlatform xsi:type="xsd:string">Test Bed</CreditCardPlatform>
    <DebitCardSupport xsi:type="xsd:boolean">false</DebitCardSupport>
    <DirectPayPlatform xsi:type="xsd:string">Disabled</DirectPayPlatform>
    <Industry xsi:type="xsd:string">eCommerce</Industry>
    <SupportedCurrencies SOAP-ENC:arrayType="ns1:CurrencyObject[0]" xsi:type="ns1:CurrencyObjectArray"/>
    </getAccountDetailsReturn>

Name Type Description
CreditCardPlatform string Name of Card Processing Platform, "Disabled" if no credit card support
Industry string Account Industry (eCommerce, Mail Order, Retail, Restaurant, Hotel)
CheckPlatform string Name of Check Processor, "Disabled" if no support for checks.
CardholderAuthentication string Integrated cardholder authentication (Verified by Visa or MC 3D Secure)
DebitCardSupport boolean True if merchant has support for processing pin based debit cards
DirectPayPlatform string Name of the direct payment platform if supported
%CurrencyObject% object Array of currencies supported by merchant. Empty if using a non-multicurrency enabled credit card processor.

Change Log

Version Description
1.2 Added DebitCardSupport and DirectPayPlatform parameters
1.1 Soap 1.1 Release

Address

Contains customer contact information.

This object contains all customer contact information including telephone number, fax number and email address.

Places Used

Properties

Example Object

    <?php
    // for directions on how to set up the  
    // WSDL link and create "$token" and "$client,"
    // see: [https://help.usaepay.info/developer/soap-api/howto/php/](https://help.usaepay.info/developer/soap-api/howto/php/)

    $Address=array(
      'City' => 'Los Angeles',
      'Company' => 'Usaepay',
      'Country' => 'US',
      'Email' => 'support@usaepay.com',
      'FirstName' => 'PHP5',
      'LastName' => 'Example',
      'Phone' => '1-866-872-3729',
      'State' => 'CA',
      'Street' => '5500 Wilshire Blvd',
      'Street2' => 'suite 2700',
      'Zip' => '90036'
    );

    $Request=array(
      'AccountHolder' => 'Example Creator',
      'ClientIP' => '123.123.123.123',
      'CustomerID' => '123456',
      'Command' => 'Sale',
      'Details' => array(
            'Amount' => '29.00',
        'Clerk' => 'John Doe',
        'Currency' => '0',
        'Description' => 'Example for address object',
        'Discount' => '1.00',
        'Invoice' => '44539'),
      'BillingAddress' => $Address,
      'ShippingAddress' => $Address,
      'CreditCardData' => array(
        'CardNumber' => '4444555566667779',
        'CardExpiration' => '0909',
        'AvsStreet' => '1234 Main Street',
        'AvsZip' => '99281',
        'CardCode' => '999')
    );

    $Response=$this->client->runTransaction($this->token, $Request);

    $TransactionObject=$this->client->getTransaction($this->token, $Response->RefNum);

    echo $TransactionObject->BillingAddress->City;

    ?>

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

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

    <BillingAddress xsi:type="ns1:Address">
    <City xsi:type="xsd:string">Los Angeles</City>
    <Company xsi:type="xsd:string">Usaepay</Company>
    <Country xsi:type="xsd:string">US</Country>
    <Email xsi:type="xsd:string">support@usaepay.com</Email>
    <Fax xsi:type="xsd:string"></Fax>
    <FirstName xsi:type="xsd:string">XML</FirstName>
    <LastName xsi:type="xsd:string">Example</LastName>
    <Phone xsi:type="xsd:string">1-866-872-3729</Phone>
    <State xsi:type="xsd:string">CA</State>
    <Street xsi:type="xsd:string">5500 Wilshire Blvd</Street>
    <Street2 xsi:type="xsd:string">suite 2700</Street2>
    <Zip xsi:type="xsd:string">90036</Zip>
    </BillingAddress>

Name Type Description
FirstName String Customer's First Name
LastName String Customer's Last Name
Company String Company or Organization Name
Street String Street Address Line 1
Street2 String Street Address Line 2
City String City
State String State or Province
Zip String Zip or Postal Code
Country String Country
Phone String Telephone Number
Fax String Fax Number
Email String Email Address

BatchSearchResult

Contains results of a batch search.

This object is returned by the developer:soap:methods:searchBatches method. It describes the result of the search, including the total number of batches matched, the number being returned, and an array of BatchStatus objects

Places Used

Properties

Example Object

    Dim result As usaepay.BatchSearchResult = New usaepay.BatchSearchResult
            result = client.searchBatches(token, search, matchAll, start, limit, sort)
            MsgBox(result.BatchesMatched)

    usaepay.BatchSearchResult result = new usaepay.BatchSearchResult();

                try
                {
                    result = client.searchBatches(token, search, matchAll, start, limit, sort);

                    MessageBox.Show(string.Concat(result.BatchesMatched));

                }

Name Type Description
BatchesMatched integer Total number of batches matched
BatchesReturned integer Number of batches returned in this result set
StartIndex integer The starting index used (defaults to 0)
Limit integer The max number batches to return in each result set.
%BatchStatus% array An array BatchStatus objects for the matched batches

BatchStatus

Contains information about a batch awaiting settlement.

This object contains information about a batch of transactions that has been authorized and is awaiting settlement. It is returned when attempting to determine the status of a batch using the getBatchStatus method.

This should reflect the same information contained in the Batch Manager section of the merchant console.

Places Used

Properties

Example Object

    <?php
    // for directions on how to set up the  
    // WSDL link and create "$token" and "$client,"
    // see: [https://help.usaepay.info/developer/soap-api/howto/php/](https://help.usaepay.info/developer/soap-api/howto/php/)

       $BatchStatus=$this->client->getBatchStatus($this->token, $BatchRefNum);

       echo $BatchStatus->Status;
    ?>

    Dim result as usaepay.BatchStatus = New usaepay.BatchStatus

            result = client.getBatchStatus(token, BatchRefNum)
            MsgBox(result.Status)

    usaepay.BatchStatus result = new usaepay.BatchStatus();

                try
                {
                    result = client.getBatchStatus(token, BatchRefNum);

                    MessageBox.Show(string.Concat(result.Status));

                }

    <getBatchStatusReturn xsi:type="ns1:BatchStatus">
    <BatchRefNum xsi:type="xsd:string">1936</BatchRefNum>
    <Closed xsi:type="xsd:string"></Closed>
    <CreditsAmount xsi:type="xsd:double">0</CreditsAmount>
    <CreditsCount xsi:type="xsd:integer">0</CreditsCount>
    <NetAmount xsi:type="xsd:double">245</NetAmount>
    <Opened xsi:type="xsd:string">04/30/2008T11:26:15</Opened>
    <SalesAmount xsi:type="xsd:double">245</SalesAmount>
    <SalesCount xsi:type="xsd:integer">20</SalesCount>
    <Scheduled xsi:type="xsd:string"></Scheduled>
    <Sequence xsi:type="xsd:integer">1</Sequence>
    <Status xsi:type="xsd:string">Open</Status>
    <TransactionCount xsi:type="xsd:integer">20</TransactionCount>
    <VoidsAmount xsi:type="xsd:double">0</VoidsAmount>
    <VoidsCount xsi:type="xsd:integer">0</VoidsCount>
    </getBatchStatusReturn>

Name Type Description
BatchKey string Batch reference number (assigned by the gateway).
BatchRefNum string A unique batch reference number assigned by the gateway.
Sequence integer Batch sequence number
Status string Status of this batch (ie: open, closing, closed)
Opened string Date/time the batch was opened (first transaction was run)
Closed string Date/time the batch was closed (if it has been closed)
Scheduled string Date/time the batch is scheduled to close
TransactionCount integer Number of transactions in the batch
SalesCount integer Number of sales in the batch
CreditsCount integer Number of credits in the batch
VoidsCount integer Number of voids in the batch
SalesAmount double Dollar amount of the sales
CreditsAmount double Dollar amount of the credits
NetAmount double Dollar amount of the sales-credits
VoidsAmount double Dollar amount of the voids

Change Log

Version Description
1.7 Added BatchKey type string. Changed BatchRefNum to type string
1.2 Renamed BatchNum Parameter to BatchRefNum

BatchUploadStatus

Contains information on an uploaded batch.

This object contains details on an uploaded batch and describes the status of a batch of transactions that has been uploaded for authorization.

Places Used

Properties

Example object

    <?php
    // for directions on how to set up the  
    // WSDL link and create "$token" and "$client,"
    // see: [https://help.usaepay.info/developer/soap-api/howto/php/](https://help.usaepay.info/developer/soap-api/howto/php/)

      $BatchUploadStatus = $client->getBatchUploadStatus($this->token, $UploadRefNum);
      echo $BatchUploadStatus->Status;
    ?>

    Dim res As usaepay.BatchUploadStatus = New usaepay.BatchUploadStatus
            res = client.getBatchUploadStatus(token, uploadrefnum)
            MsgBox(res.Status)

    try
                {
                    res = client.getBatchUploadStatus(token, uploadrefnum);
                    MessageBox.Show(string.Concat(res.Status));
                }

    <getBatchUploadStatusReturn xsi:type="ns1:BatchUploadStatus">
    <Approved xsi:type="xsd:integer">0</Approved>
    <UploadRefNum xsi:type="xsd:string">440</UploadRefNum>
    <Declined xsi:type="xsd:integer">0</Declined>
    <Errors xsi:type="xsd:integer">0</Errors>
    <Finished xsi:type="xsd:string"></Finished>
    <Remaining xsi:type="xsd:integer">102</Remaining>
    <Started xsi:type="xsd:string">2008-03-19 09:55:19</Started>
    <Status xsi:type="xsd:string">Paused</Status>
    <Transactions xsi:type="xsd:integer">102</Transactions>
    </getBatchUploadStatusReturn>

Name Type Description
UploadRefNum string Upload reference number (assigned by the gateway).
Status String Current status of the upload batch.
Started String Date and time the batch upload was initiated.
Finished String Date and time the batch upload was completed.
Transactions Integer Total number of transactions in the upload batch.
Remaining Integer Number transactions remaining to be run.
Approved Integer Number of transactions that have been approved.
Declined Integer Number of transactions that have been declined.
Errors Integer Number of transactions that resulted in errors.

Change Log

Version Change
1.7 Changed UploadRefNum to type string
1.2 Renamed BatchNum parameter to UploadRefNum
1.1 Soap 1.1 Release

CheckData

Contains information for electronic check transactions.

This object is used for electronic check processing and includes all of the fields required for processing a check transaction.

Places Used

Properties

Example Object

    <?php
    // for directions on how to set up the  
    // WSDL link and create "$token" and "$client,"
    // see: [https://help.usaepay.info/developer/soap-api/howto/php/](https://help.usaepay.info/developer/soap-api/howto/php/)

    $CheckData=array(
        'CheckNumber' => '321',
        'Account' => '123456',
        'Routing' => '123456789',
        'AccountType' => 'Savings',
        'DriversLicense' => '123123123',
        'DriversLicenseState' => 'NA',
        'RecordType' => 'ARC'
    );      

    $Request=array(
      'AccountHolder' => 'Example Creator',
      'ClientIP' => '123.123.123.123',
      'CustomerID' => '123456',
      'Command' => 'Check',
      'Details' => array(
            'Amount' => '29.00',
        'Clerk' => 'John Doe',
        'Currency' => '0',
        'Description' => 'Example for CheckData object',
        'Discount' => '1.00',
        'Invoice' => '44539'),
      'CheckData' => $CheckData
    );

    $Response=$this->client->runTransaction($this->token, $Request);

    $TransactionObject=$this->client->getTransaction($this->token, $Response->RefNum);

    echo $TransactionObject->CheckData->AccountType;

    ?>

    Dim tran As usaepay.TransactionRequestObject = new usaepay.TransactionRequestObject
    Dim CheckData As  usaepay.CheckData = new usaepay.CheckData
    CheckData.Account = "1112223333"
    CheckData.Routing = "123456789"
    CheckData.DriversLicense = "D5555555"
    CheckData.DriversLicenseState = "CA"
    tran.CheckData = CheckData

    usaepay.TransactionRequestObject tran = new usaepay.TransactionRequestObject();

                tran.CheckData = new usaepay.CheckData();
                tran.CheckData.Account = "1112223333";
                tran.CheckData.Routing = "123456789";
                tran.CheckData.DriversLicense = "D5555555";
                tran.CheckData.DriversLicenseState = "CA";

    <CheckData xsi:type="ns1:CheckData">
    <Account xsi:type="xsd:string">XXXXX3456</Account>
    <AccountType xsi:type="xsd:string">Savings</AccountType>
    <CheckNumber xsi:type="xsd:integer">321</CheckNumber>
    <DriversLicense xsi:type="xsd:string">XXXXX3123</DriversLicense>
    <DriversLicenseState xsi:type="xsd:string">NA</DriversLicenseState>
    <RecordType xsi:type="xsd:string">ARC</RecordType>
    <Routing xsi:type="xsd:string">XXXXX6789</Routing>
    </CheckData>

Name Type Description
CheckNumber Integer Check number of check being used for transaction.
Routing String Nine digit bank routing number.
Account String Bank account number.
AccountType String Checking or Savings - if left blank, default is Checking.
DriversLicense String Driver's license of checking account holder.
DriversLicenseState String Driver's license state of issue.
RecordType String Record type of electronic check transaction. Not supported by all check processors. List of Check Record Types
MICR String MICR Data for Check 21 (optional, depending on processor)
AuxOnUS String MICR Data for Check 21 (optional, depending on processor)
EpcCode String MICR Data for Check 21 (optional, depending on processor)
FrontImage String Scan of front of check, base64 encoded (optional)
BackImage String Scan of back of check, base64 (optional)
SSN String Customer Social Security Number

Change Log

Version Change
1.7 Added SSN, ImageEncoding

CheckTrace

Electronic check transaction tracking data.

Tracking data for an electronic check transaction that provides the details and status of a check transaction.

Check transactions can change status several times, including being returned by the customer's bank. Make sure to check the status of a transaction for 1-2 weeks after a transaction has posted. Typically the reason for a return will be contained in the BankNote parameter.

Properties

Example Object

    Dim trace As usaepay.CheckTrace = New usaepay.CheckTrace

            trace = client.getCheckTrace(token, refnum)

            MsgBox("Tracking Number: " & trace.TrackingNum)

    usaepay.CheckTrace trace = new usaepay.CheckTrace();

                try
                {
                    trace = client.getCheckTrace(token,refnum);

                    MessageBox.Show(string.Concat(trace.TrackingNum));

                }

Name Type Description
Status string Text description of the status code.
StatusCode string A single letter code indicating the status of a transaction.
TrackingNum string Reference number assigned by check processor.
Effective string Date check was originally posted.
Processed string Date check was received by processor.
Settled string Date check was originally settled.
Returned string Date check was returned.
ReturnCode string
Reason string
BankNote string Note from checking account holder's bank. Typically this note will explain the reason for a returned check, but it may also indicate future changes to routing/account number even if the electronic check transaction was approved. For example, if the customer's bank has been bought by another bank, the original routing number will only remain valid for about a year. During this period, the bank will send back a note indicating the new routing number.

CreditCardData

This object contains credit card specific information for a transaction.

When retrieving stored CreditCardData from the gateway with a function like getTransaction, many of the properties such as CardNumber, CardExpiration and MagStripe will be masked for security reasons. Full, unmasked, credit card data can not be retrieved via the Soap API.

Places Used

Properties

Example Object

    <?php
    // for directions on how to set up the  
    // WSDL link and create "$token" and "$client,"
    // see: [https://help.usaepay.info/developer/soap-api/howto/php/](https://help.usaepay.info/developer/soap-api/howto/php/)

    $CreditCardData=array(
        'CardNumber' => '4444555566667779',
        'CardExpiration' => '0909',
        'AvsStreet' => '1234 Main Street',
        'AvsZip' => '99281',
        'CardCode' => '999'
    );      

    $Request=array(
      'AccountHolder' => 'Example Creator',
      'ClientIP' => '123.123.123.123',
      'CustomerID' => '123456',
      'Command' => 'Sale',
      'Details' => array(
            'Amount' => '29.00',
        'Clerk' => 'John Doe',
        'Currency' => '0',
        'Description' => 'Example for CreditCardData object',
        'Discount' => '1.00',
        'Invoice' => '44539'),
      'CreditCardData' => $CreditCardData
    );

    $Response=$this->client->runTransaction($this->token, $Request);

    $TransactionObject=$this->client->getTransaction($this->token, $Response->RefNum);

    echo $TransactionObject->CreditCardData->AvsZip;

    ?>

    Dim tran As usaepay.TransactionRequestObject = New usaepay.TransactionRequestObject
            tran.CreditCardData = New usaepay.CreditCardData
            tran.CreditCardData.CardNumber = "4444555566667779"
            tran.CreditCardData.CardExpiration = "0913"
            tran.CreditCardData.CardCode = "999"

    usaepay.TransactionRequestObject tran = new usaepay.TransactionRequestObject();

    tran.CreditCardData = new usaepay.CreditCardData();
    tran.CreditCardData.CardNumber = "4444555566667779";
    tran.CreditCardData.CardExpiration = "0909";

    <CreditCardData xsi:type="ns1:CreditCardData">
    <AvsStreet xsi:type="xsd:string">1234 Main Street</AvsStreet>
    <AvsZip xsi:type="xsd:string">99281</AvsZip>
    <CardCode xsi:type="xsd:string">XXX</CardCode>
    <CardExpiration xsi:type="xsd:string">XXXX</CardExpiration>
    <CardNumber xsi:type="xsd:string">XXXXXXXXXXXX7779</CardNumber>
    <CardPresent xsi:type="xsd:boolean">false</CardPresent>
    <CardType xsi:type="xsd:string">V</CardType>
  <DataSource xsi:type="xsd:string">Contactless</DataSource>
    <InternalCardAuth xsi:type="xsd:boolean">false</InternalCardAuth>
    <MagStripe xsi:type="xsd:string"></MagStripe>
    <MagSupport xsi:type="xsd:string"></MagSupport>
    <Pares xsi:type="xsd:string"></Pares>
    <TermType xsi:type="xsd:string"></TermType>
    </CreditCardData>

Name Type Description
CardType string Card Type - describes card issuer (Visa, MC, Amex, Discover). Read only property (ignored if sent as a parameter to transaction methods).
CardNumber string Card Number
CardExpiration string Expiration Date - Should be set to 4 digit MMYY.
CardCode string CVV2/CID card code value from back of card. Set to -2 if the code is not legible, -9 if the code is not on the card.
AvsStreet string Billing address associated with card, used by AVS.
AvsZip string Billing zipcode associated with card, used by AVS.
CardPresent boolean Indicates if the card is present during the transaction (ie: the card was swiped at a POS terminal). Used to indicate retail.
MagStripe string Track 1 and/or Track 2 data for swiped transactions. For unencrypted swipers send the raw data. For encrypted swipers please look at end to end encryption
DataSource string Entry mode of transaction. (Contactless, Card Not Present- Manually Keyed, Card Swiped, Chip Read)
DUKPT string DUKPT encrypted pin block. Only required for pin debit transactions. The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the Pin Pad serial number and transaction counter.
Signature string Signature capture image. Base64 encoded.
TermType string Terminal type (POS, StandAlone, Unattended, or Unkown). May be left blank if unknown.
MagSupport string Indicates whether software has support for mag swipe (Yes, No, Unknown).
XID string XID value received from 3rd party Visa VPAS or MC UCAF.
CAVV string CAVV value received from 3rd party Visa VPAS or MC UCAF.
ECI integer ECI value.
InternalCardAuth boolean Use gateway based authentication for Visa VPAS or MC UCAF.
Pares string Pares returned by client after successful

Change Log

Version Change
1.7 Added DataSource type String(Return Only)
1.1 Added DUKPT parameter for pin-debit transactions, Signature parameter for signature capture.

CreditCardToken

This object describes a tokenized credit card.

Places Used

Properties

Name Type Description
CardRef string Unique token representing card
CardExpiration string Expiration Date of credit card
CardNumber string Masked card number
CardType string Type of card

Change Log

Version Description
1.6 Object added in this version.

CurrencyObject

Describes a currency supported by the merchant's account.

This object describes a currency supported by the merchant. For a full list of all currencies supported by the gateway see the Currency Code list.

To add support for additional currencies to your account, please contact customer service.

Places Used

Properties

Example Object

    <?php
    // for directions on how to set up the  
    // WSDL link and create "$token" and "$client,"
    // see: [https://help.usaepay.info/developer/soap-api/howto/php/](https://help.usaepay.info/developer/soap-api/howto/php/)

    //Note: getSupportedCurrencies returns an array of currency
    //objects.  Not a single object with all supported currencies.

    $CurrencyObjects=$this->client->getSupportedCurrencies($this->token);

    echo $CurrencyObjects[0]->Currency;

    ?>

    Dim response() As usaepay.CurrencyObject


            response = client.getSupportedCurrencies(token)
            MsgBox(response.Length)

    try
                {
                    usaepay.CurrencyObject[] currency = client.getSupportedCurrencies(token);
                    MessageBox.Show(string.Concat(currency.Length));
                }

    <item xsi:type="ns1:CurrencyObject">
    <Currency xsi:type="xsd:string">Australian Dollars</Currency>
    <DecimalPlaces xsi:type="xsd:integer">2</DecimalPlaces>
    <NumericCode xsi:type="xsd:integer">36</NumericCode>
    <Rate xsi:type="xsd:double">1.1284389176</Rate>
    <TextCode xsi:type="xsd:string">AUD</TextCode>
    </item>

Name Type Description
NumericCode integer 3 digit numeric currency code to be used when processing transactions in the corresponding currency.
TextCode string 3 character currency code (ie: USD or EUR).
Currency string Full name of currency (ie: US Dollars or Euros).
Rate double Currency's current conversion rate. This is the conversion rate to the merchant's specified settling currency.
DecimalPlaces integer Number of positions to the right of the decimal (or whole units separator). Used for rounding (ie for USD 12.88, DecimalPlaces=2, for Japanese Yen 512 DecimalPlaces=0).

CustomerObject

Contains customer data.

This object contains all relevant customer data including the CustNum (a unique customer number assigned by the gateway), CustID (a merchant assigned customer ID), as well as customer name, address, recurring billing status and schedule, and any other relevant data.

Places Used

Properties

    <?php
    // for directions on how to set up the  
    // WSDL link and create "$token" and "$client,"
    // see: [https://help.usaepay.info/developer/soap-api/howto/php/](https://help.usaepay.info/developer/soap-api/howto/php/)

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

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

    $CustomerNumber=$this->client->addCustomer($this->token,$CustomerObject);

    $CustomerObject= $this->client->getCustomer($this->token, $CustomerNumber);
    echo $CustomerObject->CustNum;
    ?>

    <getCustomerReturn xsi:type="ns1:CustomerObject">
    <Amount xsi:type="xsd:double">1.00</Amount>
    <BillingAddress xsi:type="ns1:Address">
     <City xsi:type="xsd:string">Los Angeles</City>
     <Company xsi:type="xsd:string">UsaEpay</Company>
     <Country xsi:type="xsd:string">US</Country>
     <Email xsi:type="xsd:string">support@usaepay.com</Email>
     <Fax xsi:type="xsd:string">333-333-3334</Fax>
     <FirstName xsi:type="xsd:string">Example</FirstName>
     <LastName xsi:type="xsd:string">Generator</LastName>
     <Phone xsi:type="xsd:string">333-333-3333</Phone>
     <State xsi:type="xsd:string">CA</State>
     <Street xsi:type="xsd:string">1234 main st</Street>
     <Street2 xsi:type="xsd:string">Suite #123</Street2>
     <Zip xsi:type="xsd:string">12345</Zip>
    </BillingAddress>
    <CustNum xsi:type="xsd:string">21727</CustNum>
    <CustomData xsi:type="xsd:string">
    </CustomData>
    <CustomFields SOAP-ENC:arrayType="ns1:FieldValue[2]" xsi:type="ns1:FieldValueArray">
     <item xsi:type="ns1:FieldValue">
      <Field xsi:type="xsd:string">Example</Field>
      <Value xsi:type="xsd:string">Field</Value>
     </item>
    </CustomFields>
    <CustomerID xsi:type="xsd:string">156244967</CustomerID>
    <Created xsi:type="xsd:string">2008-05-08 13:40:35</Created>
    <Description xsi:type="xsd:string">Weekly Bill</Description>
    <Enabled xsi:type="xsd:boolean">false</Enabled>
    <Modified xsi:type="xsd:string">2008-05-08 13:40:35</Modified>
    <Next xsi:type="xsd:string">2012-01-21T12:00:00</Next>
    <Notes xsi:type="xsd:string">Any notes go here</Notes>
    <NumLeft xsi:type="xsd:integer">50</NumLeft>
    <OrderID xsi:type="xsd:string">1707022452</OrderID>
    <PaymentMethods SOAP-ENC:arrayType="ns1:PaymentMethod[1]" xsi:type="ns1:PaymentMethodArray">
     <item xsi:type="ns1:PaymentMethod">
      <CheckData xsi:type="ns1:CheckData">
       <Account xsi:nil="true"/>
       <Routing xsi:nil="true"/>
      </CheckData>
      <CreditCardData xsi:type="ns1:CreditCardData">
       <AvsStreet xsi:type="xsd:string">1234 main st</AvsStreet>
       <AvsZip xsi:type="xsd:string">12345</AvsZip>
       <CardExpiration xsi:type="xsd:string">XXXX</CardExpiration>
       <CardNumber xsi:type="xsd:string">XXXXXXXXXXXX7779</CardNumber>
       <CardType xsi:type="xsd:string">V</CardType>
      </CreditCardData>
      <Expires xsi:type="xsd:string">2008-05-08</Expires>
      <MethodID xsi:type="xsd:string">7353</MethodID>
      <MethodName xsi:type="xsd:string">My Visa</MethodName>
      <SecondarySort xsi:type="xsd:integer">1</SecondarySort>
     </item>
    </PaymentMethods>
    <ReceiptNote xsi:type="xsd:string">Example Receipt Note</ReceiptNote>
    <Schedule xsi:type="xsd:string">Weekly</Schedule>
    <SendReceipt xsi:type="xsd:boolean">true</SendReceipt>
    <Source xsi:type="xsd:string">Recurring</Source>
    <Tax xsi:type="xsd:double">0</Tax>
    <User xsi:type="xsd:string">(Auto)</User>
    </getCustomerReturn>

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

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

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

                customer.PaymentMethods = payMethod;

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

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

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

            customer.PaymentMethods = payMethod

Name Type Description
CustNum string Customer Number (System assigned)
CustKey string Customer Number (System assigned)
CustomerID string Customer ID (Merchant assigned)
%BillingAddress% object Billing Address
%PaymentMethod% array Array of PaymentMethod objects. Multiple credit cards or ACH accounts may be stored for each customer.
Notes string Notes (visible to merchant only).
CustomData string Custom data is a raw text field, please serialize and encode (ie: base64) your data so that complex types are stored and retrieved correctly.
%CustomFields% array Array of field values containing the merchant defined customer fields. These fields are defined in the merchant console.
URL string URL for customers website
Created string Date/Time customer was created (Read Only)
Modified string Date/Time customer was last changed (Read Only)
Enabled boolean Notes whether or not a customer has been enabled for a recurring billing cycle. The customer billing does not need to be enabled to run one time transactions via the runCustomerTransaction method.
Schedule string Recurring billing schedule, if any. Possible values include: daily, weekly, bi-weekly (every two weeks), monthly, bi-monthly (every two months), quarterly, bi-annually (every six months), annually, first of month, last day of month.
NumLeft string Number of transactions remaining in customer's recurring billing cycle. "-1" indicates unlimited transactions.
Next string Date of customer's next scheduled transaction.
Amount double Total Amount to be billed in recurring billing cycle.
Tax double Portion of Amount that is Tax
Currency string Numeric currency code for Amount. (Only needed if multicurrency merchant account)
Description string Description of transaction.
OrderID string Transaction Order ID
User string Merchant username assigned to billing.
Source string Name of source key assigned to billing.
SendReceipt boolean Send client a receipt.
ReceiptNote string Note to send on receipt.
Failures integer Number of failures since last approval.
PriceTier string Name of customer price tier
TaxClass string Tax Class (Group)
LookupCode string Lookup code from customer/member id card. Either barcode or Magnetic stripe. Can be assigned by merchants. Defaults to system assigned if left blank.

Change Log

Version Change
1.7 Added Custkey type string

CustomerSearchResult

Contains customer search data.

This object is returned by the searchCustomers method. It describes the result of the search, including the total number of customers matched, the number being returned, and an array of CustomerObjects.

Places Used

Properties

Example Object

    Dim response As usaepay.CustomerSearchResult = New usaepay.CustomerSearchResult

            response = client.searchCustomers(token, search, matchAll, "0", "10", "fname")
            MsgBox(response.CustomersMatched)

    usaepay.CustomerSearchResult response = new usaepay.CustomerSearchResult();

                try
                {
                    response = client.searchCustomers(token, search, matchAll, "0", "10", "fname");

                    MessageBox.Show(response.CustomersMatched);

                }

Name Type Description
CustomersMatched integer Total number of customers matched by search criteria.
CustomersReturned integer Total number of customers contained in search result.
StartIndex integer The index where this result set begins (default is 0).
Limit integer The maximum number of customers to be returned in the search.
%CustomerObject% array An array of CustomerObjects matched by search criteria.

Change Log

Version Description
1.1 Method added prior to soap-1.1

CustomerTransactionRequest

Used to run a new customer transaction.

This object contains the data needed to run a new stored customer transaction.

Places Used

Properties

Example Object

Name Type Description
Command string Processing command to run. Possible values: Sale, AuthOnly, Credit, Check and CheckCredit. If a blank is passed, the default value is Sale for credit card or Check for checks
IgnoreDuplicate boolean Do not check for duplicate transaction. Set to "true" if you would like to override the duplicate transaction handling.
%Details% object Transaction details: amount, clerk, currency,
ClientIP string IP Address of client.
CustReceipt boolean Customer Receipt. Set to "true" if you would like the gateway to send an email to customer.
CustReceiptEmail string Email address to receipt to. If left blank, the receipt will be sent to the email address stored in the customer record.
CustReceiptName string Customer Receipt Template Name. Specify the name of the template to use. (Optional)
MerchReceipt boolean Send Merchant Receipt. Set to "true" if you would like the gateway to send a receipt to the merchant.
MerchReceiptEmail string Email address to receipt to. Required if MerchReceipt is set to true
MerchReceiptName string Merchant Receipt Template Name. Specify the name of the template to use. (Optional)
%CustomFields% array Array of FieldValue pairs. Additional transaction api fields (ie UMtimeout) can also be passed in via this array. Any field name starting with UM is assumed to be an api field and not a custom field.
isRecurring boolean Recurring flag Signals to the platform that this transaction is a recurring billing transaction. Use with caution, can cause downgrades if not used properly. Defaults to false which causes the transaction to run as a normal card not present transaction.
InventoryLocation string ID of warehouse to draw inventory from. If blank, uses setting from source key. If no setting in source key, inventory will not be adjusted.
CardCode string CVV2/CVC card id code. PCI requirements forbid storing CVV2 value. Customer must be prompted to enter this value each time a transaction is run. This value is not required unless CVV2 validation is desired.
%LineItem% array Array of line item details
Software string Free form string that can be used by the developer to record information about their software, version, build number or operating system details. Reported on the transaction detail screen, in custom reports or via api. (optional)
XID string XID value received from 3rd party Visa VPAS or MC UCAF. Can be sent with transaction, but cannot be stored in method.
CAVV string CAVV value received from 3rd party Visa VPAS or MC UCAF. Can be sent with transaction, but cannot be stored in method.
ECI integer ECI value. Can be sent with transaction, but cannot be stored in method.

Change Log

Version Description
1.7 Added Custkey type string. Added CAVV and 3DSecure method fields.

FieldValue

Generalized Field-Value Pair

This object is used by several methods that do not have a fixed list of parameters, like runTransaction. See the documentation of the specific method for the valid field names. (Methods using this object are listed below.)

Places Used

Properties

    Dim Fields(0 To 9) As usaepay.FieldValue
            Dim i As Integer

            For i = 0 To 9
                Fields(i) = New usaepay.FieldValue
            Next i

            Fields(0).Field = "UMname"
            Fields(0).Value = "Tester Jones"
            Fields(1).Field = "UMdescription"
            Fields(1).Value = "Visual Basic For Dummies"
            Fields(2).Field = "UMamount"
            Fields(2).Value = "1.00"
            Fields(3).Field = "UMinvoice"
            Fields(3).Value = "12345"
            Fields(4).Field = "UMcard"
            Fields(4).Value = "4444555566667779"
            Fields(5).Field = "UMexpir"
            Fields(5).Value = "1212"
            Fields(6).Field = "UMstreet"
            Fields(6).Value = "1234 Main Street"
            Fields(7).Field = "UMzip"
            Fields(7).Value = "90210"
            Fields(8).Field = "UMcvv2"
            Fields(8).Value = "999"

    usaepay.FieldValue[] tran = new usaepay.FieldValue[9];

                for (int i = 0; i < 9; i++)
                {
                    tran[i] = new usaepay.FieldValue();
                }

                tran[0].Field = "UMname";           tran[0].Value = "Tester Jones";
                tran[1].Field = "UMdescription";    tran[1].Value = "runTransactionAPI sale";
                tran[2].Field = "UMamount";         tran[2].Value = "1.00";
                tran[3].Field = "UMinvoice";        tran[3].Value = "12345";
                tran[4].Field = "UMcard";           tran[4].Value = "4444555566667779";
                tran[5].Field = "UMexpir";          tran[5].Value = "1212";
                tran[6].Field = "UMstreet";         tran[6].Value = "123 Main Street";
                tran[7].Field = "UMzip";            tran[7].Value = "90046";
                tran[8].Field = "UMcvv2";           tran[8].Value = "999";

Name Type Description
Field string Name of element.
Value string Value of element.

LineItem

Contains elements needed for line item data.

Merchants can pass information about the individual line items that make up an order. This data is visible on the transaction details page. Up to 100 lines may be stored per transaction.

All fields must be passed, but may be left blank if not applicable.

Properties

Example Object

    Dim line as usaepay.LineItem = new usaepay.Lineitem
    line.SKU = "123456"
    line.ProductRefNum = "90476"
    line.ProductName = "QuickBook"  
    line.Description = "test"   
    line.UnitPrice = "100"
    line.Qty = "5"

    usaepay.LineItem line = new usaepay.Lineitem();
    line.SKU = "123456";
    line.ProductRefNum = "90476";
    line.ProductName = "QuickBook";     
    line.Description = "test";  
    line.UnitPrice = "100";
    line.Qty = "5";     

Name Type Description
ProductRefNum string Unique ID of the product assigned by the gateway (Optional)
ProductKey string Unique ID of the product assigned by the gateway
SKU string A stock-keeping unit is a unique identifier for each distinct product and service that can be purchased
ProductName string Name of the product
Description string Description of product or purchase
UnitPrice string Individual price of the unit
Qty string Total number of items
Taxable boolean Taxable good flag
CommodityCode string Numeric code used to classify the good or service. See the UNSPSC for codes. (Level 3)
UnitOfMeasure string Unit that quantity is measuring. Defaults to "EA". See list of valid Unit of Measure Codes (Level 3)
DiscountAmount string Amount line item was discounted (Level 3)
DiscountRate string The rate used to calculate discount (Level 3)
TaxAmount string Tax charged for this line item (Level 3)
TaxRate string The tax rate used for this line item (Level 3)

The properties noted as "Level 3" are only necessary if merchant is processing level 3 data for business or corporate purchasing cards.

Change History

Version Change
1.7 Added ProductKey type string

Lodging Details

Contains elements needed for lodging details for a transaction.

Merchants in the Hotel/Lodging industry may need to pass through specific details about a transactions. Below are the fields for each.

Properties

Name Type Description
Folio string Guest account reference number
RoomRate string Rate of room
Nights string How many nights the reservation is for
CheckInDate string Date guest will check in.
CheckOutDate string Date guest will check out.
ExtraChargeReasons string Comment field denoting why guest was charged extra.
RoomNumber string Guests room number
CustomerCode string Reference number for the guest
LengthOfStay string How long the guest will be staying
RoomTaxRate string Tax percentage for the room type booked.
NonRoomCharges string Any charges made outside of the booking costs. (Room Service, etc.)
RoomTaxAmount string Tax amount in dollars for the room.
PreferredCustomer string Denotes if this guest is a preferred customer.
ChargeType string Denotes how guest paid for the room.
DepartureTime string Time and date guest departed.
ArrivalTime string Time and date the guest arrived

Change History

Version Change
1.7 Added Object.

PaymentMethod

Describes a customer payment method.

This object describes a customer payment method. A payment method can be a CreditCard, ACH (Electronic Check), StoredValue (gift certificate, store credit, auto-reloading prepaid card, etc), and Invoice. The payment type is specified by setting MethodType to 'CreditCard', 'ACH', 'StoredValue' or 'Invoice'. If MethodType is left blank and credit card information is provided, the type will default to 'CreditCard'. If MethodType is left blank and electronic check information is provided, the type will default to 'ACH'.

The StoredValue method can be as simple as a store credit or as complex as linking to a physical pre-paid card or gift card with a magnetic strip. For a store credit or simple balance on account, the only required field is Balance. To use the StoredValue payment method, the merchant account must have stored value transactions enabled.

The Invoice method allows a merchant to collect transactions that will be invoice at a later date. Balance is increased by the system when an Invoice transaction is received. MaxBalance specifies that maximum balance that a customer can incur before Invoice transactions are declined. Setting MaxBalance to 0 will cause the customer to have no limit. To process Invoice transactions, the merchant account must have Invoice processing enabled.

Places Used

Properties

Example Object

    Dim payMethod As usaepay.PaymentMethod = New usaepay.PaymentMethod
            payMethod.CardExpiration = "1212"
            payMethod.CardNumber = "4000100011112224"
            payMethod.AvsStreet = "123 Main st."
            payMethod.AvsZip = "90046"
            payMethod.MethodName = "My Visa"

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

Name Type Description
MethodType string Type of payment method (CreditCard, ACH, StoredValue or Invoice)
MethodID string ID of payment method. This property is ignored when adding a new payment method but required if updating an existing method.
MethodName string Label for payment method. For example "Work Visa" or "Personal Checking."
SecondarySort integer If set to value greater than 0, use this method as backup in case default fails. Secondary methods will be run in ascending order.
Created string Date and time the method was created.
Modified string Date and time the method was last modified.
Expires string Date on which payment method will expire. Do not leave blank. Format: YYYY-MM-DD
CardHolder string Name of the card holder on credit/debit card.
CardNumber string Credit card number (required for credit cards). If data is coming from a swiper, base64_encode the entire raw block read from the swiper device and put %%enc://%% at the beginning. Example: %%enc://%%AAbbCdEEaa...
CardExpiration string Credit card expiration date in YYYY-MM format. It will also accept MMYY format. (required for credit cards)
AvsStreet string Street address for AVS (address verification system). (Optional but recommended for credit cards)
AvsZip string Zip code for AVS. (Optional but recommended for credit cards)
CardCode string CVV2/CID card identification code. This code is not stored and is only used when verifying a new payment method before it is added. (Optional for credit cards)
CardType string Type of credit card (Visa, Mastercard, etc). This is a read only parameter and will be ignored if set.
XID string XID value received from 3rd party Visa VPAS or MC UCAF. Can be sent with transaction, but cannot be stored in method.
CAVV string CAVV value received from 3rd party Visa VPAS or MC UCAF. Can be sent with transaction, but cannot be stored in method.
ECI integer ECI value. Can be sent with transaction, but cannot be stored in method.
Account string ACH Bank Account Number (required for checks)
AccountType string ACH Type of Bank Account (Checking or Savings, defaults to checking)
Routing string ACH Bank Routing Number (required for checks)
DriversLicense string Drivers license number used for check guarantee (optional)
DriversLicenseState string Drivers license state (optional)
RecordType string ACH transaction type (optional, should be left blank unless instructed differently by check processor)
MaxBalance double The maximum balance that may be charged on Invoice before transactions are declined
Balance double The funds left on the account. Transactions against this payment method may not exceed this balance
AutoReload boolean Set true if StoredValue card should automatically be reloaded
ReloadSchedule string Automatic reload schedule
ReloadThreshold double Balance that will trigger an automatic reload
ReloadAmount double Amount to automatically reload
ReloadMethodID string Payment method to use for reloading card

Change Log

Version Description
1.7 Added CAVV and 3DSecure method fields. Added CardHolder field.
1.4 Add MethodType, Balance, MaxBalance, AutoReload, ReloadSchedule, ReloadThreshold, ReloadAmount, ReloadMethodID
1.3 Dropped CreditCardData and CheckData. Added Account, AccountType, DriversLicense, DriversLicenseState, RecordType, Routing, AvsStreet, AvsZip, CardCode, CardExpiration, CardNumber and CardType
1.2 Added the Created and Modified Parameters
1.1 Soap 1.1 Release

PriceTier

Object describing a product price tier.

This object represents a variable pricing tier. There are two types of price tiers: general pricing and customer specific pricing. Both types implement qty thresholds. For example, buy 1 for $9.99 or buy 10 for $8.99 each. For general price tiers the 'CustomerTier' parameter should be omitted or left blank. An example price tier for a product with a base price of 199.99 might look like:

Qty Price
10 189.99
50 169.99
100 149.99

If a customer purchased up to 9 qty of this item, the price would be $199.99 each. If they purchased from 11 to 49 the price would be $189.99 each. From 50 to 99 would be $169.99 each. 100 and above would be $149.99 each.

A customer price tier allows customer specific pricing to be set. This is done by creating price tiers with the 'CustomerTier' parameter set. The value of 'CustomerTier' is flexible and can be set to any string up to 32 characters. A customer will receive this pricing if they have a matching PriceTier parameter set on the CustomerObject. Multiple customers can be assigned to the PriceTier. An example customer price tier table for a product with a base price of $199.99:

CustomerTier Qty Price
Distributor 1 129.99
Distributor 50 109.99
Distributor 100 99.99
Employee 1 99.99

Places Used

Properties

Name Type Description
Qty string Qty threshold for price
Price string Product Price
CustomerTier string Customer based price tier identifier

Change Log

Version Description
1.4 Object added in 1.4 release

Product

Object describing a product.

This object contains all of the data needed for adding, updating, and deleting a product on the gateway.

Places Used

Properties

Name Type Description
ProductRefNum string Gateway assigned ID of product
ProductKey string Unique ID of the product assigned by the gateway
ProductID string Merchant assigned product ID
Category string Product category
SKU string Stock-Keeping Unit
UPC string Universal Product Code
Enabled boolean Enables the ability to store products
Name string Name of the product
Description string Product description
Model string Model of the product
Weight string Weight of the product
ShipWeight string Shipping weight of the product
Price double Price of the product
WholesalePrice double Wholesale price of the product
ListPrice double List price of the product
%PriceTier% object Qty and Customer based variable pricing tiers
TaxClass string Product's Tax Class
DateAvailable string Date the product is available for sale
Manufacturer string Maker of the product
PhysicalGood boolean Tangible/Shippable good.
MinQuantity integer Minimum quantity allowed
ImageURL string URL address of the product image
URL string URL of the product
%ProductInventory% object Product inventory levels
Modified string Date/time the product was last changed
Created string Date/time the product was created

Change Log

Version Description
1.7 Added ProductKey type string

ProductCategory

Object describing a product category.

This object represents a product category which is a container for products. Currently product categories can not be nested.

Places Used

Properties

Name Type Description
ProductCategoryRefNum string Gateway assign unique reference number
ProductCategoryKey string Gateway assign unique reference number
Name string Name of product category
Created string Timestamp for when the category was created
Modified string Timestamp for when the category was last modified

Change Log

Version Description
1.7 ProductCategoryKey added.
1.3 Object added in 1.3 release

ProductInventory

Object describing a product inventory at a given location.

This object represents the current inventory counts for a given location.

Places Used

Properties

Name Type Description
InventoryLocationKey string Gateway assign unique reference number
InventoryLocation string Location of Inventory (Warehouse or location name)
QtyOnHand string Count of available units in stock
QtyOnOrder string Count of units on order (scheduled to be available on DateAvailable)
DateAvailable string Date that QtyOnOrder is scheduled to arrive

Change Log

Version Description
1.3 Object added in 1.3 release

ProductSearchResult

Contains results of a products search. It describes the result of the search, including the total number of products matched, the number being returned, and an array of Product Objects.

Places Used

Properties

Name Type Description
ProductsMatched integer Total number of transactions matched
ProductsReturned integer Number of transactions returned in this result set
StartIndex integer The starting index used (defaults to 0)
Limit integer The max number transactions to return in each result set.
%Product% array An array Products for the matched criteria

Receipt

Object describing a receipt template.

This object contains all of the data needed for adding or updating a receipt template on the gateway.

Places Used

Properties

    Dim receipt As usaepay.Receipt = New usaepay.Receipt
            receipt.Name = "test receipt_VB"
            receipt.Target = "email"
            receipt.Subject = "test receipt"
            receipt.FromEmail = "devsupport@usaepay.com"
            receipt.ContentType = "text"

    usaepay.Receipt receipt = new usaepay.Receipt();
                receipt.Name = "test receipt";
                receipt.Target = "email";
                receipt.Subject = "test receipt";
                receipt.FromEmail = "devsupport@usaepay.com";
                receipt.ContentType = "text";

                string message = "Yippy Skippy";
                byte[] toencodeAsBytes = System.Text.ASCIIEncoding.ASCII.GetBytes(message);
                string returnValue = System.Convert.ToBase64String(toencodeAsBytes);
                receipt.TemplateText = returnValue;

Type Name Description
ReceiptRefNum string Gateway assigned ID of Receipt. (Ignored when adding a receipt)
Name string Name of receipt (used to identify receipt)
Target string Type of receipt output (Email or Print)
Subject string Subject line of email (Only applicable if "Target" is "Email")
FromEmail string From email address (Only applicable if "Target" is "Email")
ContentType string Content types supported by receipt (HTML, Text or Both)
TemplateHTML string HTML version of template (Base-64 Encoded)
TemplateText string Text version of template (Base-64 Encoded)

Change History

Version Change
1.7 Changed ReceiptRefNum to type string
1.3 Object added in 1.3 release

RecurringBilling

This object stores information relating to specific recurring billing cycles.

It includes the frequency, amount, start and end dates of the recurring billing schedule.

Places Used

Properties

Example Object

    Dim recurring As usaepay.RecurringBilling = New usaepay.RecurringBilling
            recurring.Amount = 10.0
            recurring.Enabled = True
            recurring.Next = "2010-09-01"
            recurring.NumLeft = "5"
            recurring.Schedule = "monthly"

            tran.RecurringBilling = recurring

    tran.RecurringBilling = new usaepay.RecurringBilling();
                tran.RecurringBilling.Amount = 10.00;
                tran.RecurringBilling.Schedule = "bi-monthly";
                tran.RecurringBilling.Next = "2010-09-01";
                tran.RecurringBilling.NumLeft = "5";
                tran.RecurringBilling.Enabled = true;

Name Type Description
Schedule string Frequency of recurring billing schedule. Possible values include: disabled, daily, weekly, bi-weekly (every two weeks), monthly, bi-monthly (every two months), quarterly, bi-annually (every six months), annually.
Next string Date this customer will be billed next. Must be formatted Year-Month-Day (ie 2011-07-04)
Expire string Date this billing entry will be disabled.
NumLeft integer Number of transactions remaining in recurring billing cycle. (Overrides the Expire parameter)
Amount double Amount to be billed in each transaction.
Enabled boolean Notes whether customer is currently enabled for recurring billing.

SearchParam

Used to create a unique search parameter.

This object is used to create a search parameter for methods such as searchTransactions and searchCustomers.

It consists of three properties: the name of the field you are searching on, the type of comparison to make, and the value. Since each method uses a unique set of search parameters, check the documentation of each method for a list of valid field names. A complete list of all methods using this object can be found below.

Places Used

Properties

Example Object

    Dim search(0) As usaepay.SearchParam

            search(0) = New usaepay.SearchParam()

            search(0).Field = "Created"
            search(0).Type = "Contains"
            search(0).Value = "2010-09-09"

    usaepay.SearchParam[] search = new usaepay.SearchParam[2];
                search[0] = new usaepay.SearchParam();
                search[1] = new usaepay.SearchParam();

                search[0].Field = "Amount";
                search[0].Type = "eq";
                search[0].Value = "12.00";

                search[1].Field = "Created";
                search[1].Type = "gt";
                search[1].Value = "2010-08-08";

Name Type Description
Field string Name of field you are searching.
Type string Search condition. Possible Values are:
- dneq -Does not Equal
- eq -Equals
- gt -Greater Than
- lt -Less Than
- gte -Greater Than or Equal To
- lte -Less Than or Equal To
- sw -Starts with
- ew -Ends with
- contains -contains
- dncontain -Does not Contain
- in -In List
- notin -Not in List
Value string Value to search on

SyncLog

A change log entry

This object describes a change that has occurred on the gateway.

Places Used

Properties

Example Object

     try
                {
                    usaepay.SyncLog[] log = client.getSyncLog(token, ObjectName, FromPosition);
                    MessageBox.Show(string.Concat(log.Length));

                }

Name Type Description
SyncPosition integer Sequential id of sync log entry
ObjectName string Object type that was changed (products, products_categories, customers, etc)
RefNum string Reference number for object that was changed (ProductRefNum, CustRefNum, etc)
ChangeDate string The date/time that the changed occurred on the gateway (all times in PST)
Action string The type of change that occurred (insert,update or delete)

SystemInfo

Contains API version, environment, data-center, time.

This object contains the API version, environment (production/sandbox/staging), data-center location, and a timestamp.

Places Used

Properties

Name Type Description
ApiVersion string Version of the API
Environment string Production, Sandbox, or Staging
Datacenter string Location of the data-center
Time string Timestamp

TransactionDetail

Contains transaction specific data.

This object is used with several transaction methods and contains important transaction specific data such as invoice number, originating terminal, total amount of transaction, portions of total alloted for tip, tax and shipping, and currency code.

Places Used

Properties

Example object

    Dim details As usaepay.TransactionDetail = New usaepay.TransactionDetail

            details.Amount = "34.50"
            details.AmountSpecified = True
            details.Description = "Example QuickSale"
            details.Invoice = "123456"

    usaepay.TransactionDetail details = new usaepay.TransactionDetail();

                details.Amount = 34.50;
                details.AmountSpecified = true;
                details.Description = "Example QuickSale";
                details.Invoice = "123456";

Name Type Description
Invoice string Transaction invoice number. Will be truncated to 10 characters. If this field is not provided, the system will submit the RefNum in its place.
PONum string Purchase Order Number for commercial card transactions - 25 characters. (Required for Level 2 & 3)
OrderID string Transaction order ID. This field should be used to assign a unique order id to the transaction. The order ID can support 64 characters.
SessionID string Optional Session ID used for customer analytics and fraud prevention. Must be get generated using the getSession method. See the profiling guide for more information
Clerk string Sales Clerk. Optional value indicating the clerk/person processing transaction, for reporting purposes.
Terminal string Terminal Name. Optional value indicating the terminal used to process transaction, for reporting purposes.
Table string Restaurant Table Number. Optional value indicating the restaurant table, for reporting purposes
LaneID string POS identification number set by merchant.
Description string Transaction description.
Comments string Comments. Free form text.
AllowPartialAuth boolean Allow a partial authorization if full amount is not available (Defaults to false)
Amount double Total billing amount. (Subtotal+Tax+Tip+Shipping-Discount=Amount.)
Currency string Currency Code. 3 digit currency code of total amount.
Tax double Portion of total amount that is tax. (Required for Level 2 & 3)
Tip double Portion of total amount that is tip.
NonTax boolean Determines whether a transaction is non-taxable.
Shipping double Portion of total amount that is shipping charges. (Required for Level 3)
ShipFromZip double Zipcode that the order is shipping from. (Required for Level 3)
Discount double Amount of discount.
Duty double Amount of duty charged. (Required for Level 3)
Subtotal double The amount of the transaction before tax, tip, shipping and discount have been applied.
CashBack string Denotes the amount of cashback customer requested.
DigitalGoods string Denotes the products were virtual or physical

Change Log

Version Change
1.7 Added CashBack type string, DigitalGoods type string, LaneID type string

TransactionObject

Contains all transaction data.

This object contains all of the data on a transaction. Some fields are masked for security reasons and some fields are specific to credit card or electronic check transactions.

Some information stored in this object is important for security reasons such as the username of the person who processed the transaction, the IP address of the server from which it was submitted and the source key that the transaction was processed under.

Places Used

Properties

Example Object

    Dim response As usaepay.TransactionObject

            response = client.getTransaction(token, refnum)

            MsgBox("Transaction Type: " & response.TransactionType)

    usaepay.TransactionObject tran = new usaepay.TransactionObject();

                try
                {
                    tran = client.getTransaction(token, refnum);
                    MessageBox.Show(string.Concat("Transaction RefNum: ",
                                tran.Response.RefNum));


                }

Name Type Description
Status string Status of specified transaction.
%TransactionResponse% object Returns a TransactionResponse object containing the results of the transaction and all relevant data.
TransactionType string Type of transaction. (Sale, Credit, Void, AuthOnly, etc.)
%CheckTrace% object Tracking data for check transactions. Includes tracking number, effective posting date, date processed, date settled, date returned and bank notes.
DateTime string Date/time transaction was originally submitted.
AccountHolder string Name of the account holder.
%Details% object Transaction details: amount, clerk, currency, etc.
%CreditCardData% object CreditCardData. Required for credit card transactions.
%CheckData% object CheckData. Required for electronic check processing.
User string The username of the person who processed this transaction.
Source string The name of the source key that this transaction was processed under.
ServerIP string IP Address of the server that submitted the transaction to the gateway.
ClientIP string IP Address of client (if passed on from the server).
CustomerID string Customer ID
%BillingAddress% object Billing Address
%ShippingAddress% object Shipping Address
%CustomFields% array Array of FieldValue pairs. Additional transaction api fields (ie UMtimeout) can also be passed in via this array. Any field name starting with UM is assumed to be an api field and not a custom field.
%LineItem% array Array of line item details
%LodgingDetails% object Object which contains lodging details.

Change Log

Version Description
1.7 Added LodgingDetails property.
1.2 Added CustomFields property.
1.1 Soap 1.1 Release (no changes)
1.0 Response property added

TransactionRequestObject

Used to run a new transaction.

This object contains the data needed to run a new transaction, including sale, credit, void and authonly.

Places Used

Properties

Example object

    Dim tran As usaepay.TransactionRequestObject = New usaepay.TransactionRequestObject

            tran.CreditCardData = New usaepay.CreditCardData
            tran.CreditCardData.CardNumber = "4444555566667779"
            tran.CreditCardData.CardExpiration = "0913"
            tran.CreditCardData.CardCode = "999"

            tran.Details = New usaepay.TransactionDetail
            tran.Details.Amount = 9.02
            tran.Details.AmountSpecified = True
            tran.Details.Invoice = "434534"
            tran.Details.Description = "Example transaction"

            tran.Command = "sale"

    usaepay.TransactionRequestObject tran = new usaepay.TransactionRequestObject();

    tran.Command = "cc:sale";
    tran.Details =  new usaepay.TransactionDetail();
    tran.Details.Amount = 1.00;
    tran.Details.AmountSpecified = true;
    tran.Details.Invoice = "1234";
    tran.Details.Description = "Example Transaction";

    tran.CreditCardData = new usaepay.CreditCardData();
    tran.CreditCardData.CardNumber = "4444555566667779";
    tran.CreditCardData.CardExpiration = "0909";

Name Type Description
Command string Processing Command. Possible values are: sale, credit, void, creditvoid, authonly, capture, postauth, check and checkcredit. Default is sale.
IgnoreDuplicate boolean Do not check for duplicate transaction. Set to "true" if you would like to override the duplicate transaction handling.
AuthCode string Original Authorization Code. Authorization Code obtained "offline" (ie telephone authorization). Only required for PostAuth.
RefNum string Original Transaction Reference Number. The RefNum received when a transaction was authorized via either the "sale" or "authonly" commands. Required for void and capture commands. Can also use TransKey here.
AccountHolder string Name of the account holder.
%Details% object Transaction details: amount, clerk, currency, etc.
%CreditCardData% object CreditCardData. Required for credit card transactions.
%CheckData% object CheckData. Required for electronic check processing.
ClientIP string IP Address of client.
CustomerID string Customer ID.
%BillingAddress% object Billing Address
%ShippingAddress% object Shipping Address
CustReceipt boolean True/False. True will cause a customer receipt to be sent.
CustReceiptName string Name of the receipt template to use. Defaults to the standard customer receipt.
%RecurringBilling% object RecurringBilling. Object describing if recurring billing cycle should be created if initial transaction is approved.
%LineItem% array Array of line item details
%LodgingDetails% object Object which contains lodging details.
%CustomFields% array Array of FieldValue pairs. Additional transaction api fields (ie UMtimeout) can also be passed in via this array. Any field name starting with UM is assumed to be an api field and not a custom field.
IfAuthExpired string Controls what will happen if the authorization has expired. Possible values are:
- Error will block the capture request
- ReAuth will attempt to reauthorize the funds
- Capture will ignore the authorization date and proceed with capture.

If left blank, Capture will be assumed. The amount of time between an authorization expires is controlled by the Expire Auths After setting.
AuthExpireDays string Sets number of days before an authorization expires.
ReleaseFunds boolean Set to true to release funds. Only used for voidTransaction.
IsRecurring boolean Flags a credit card transaction as a recurring payment when sent to the platforms for processing. This is not related to the RecurringBilling object above and it does not tie into the gateway's recurring billing system. Rather, this flag should be used by developers who are initiating the recurring transactions from within their own system and need to indicate that it is recurring.
Software string Free form string that can be used by the developer to record information about their software, version, build number or operating system details. Reported on the transaction detail screen, in custom reports or via api.
SaveCard boolean Set to "True" to tokenize card.

Change Log

Version Change
1.7 Added SaveCard type Boolean, LodgingDetails type LodgingDetails, AuthExpireDays type string, EntryMode type string, ReleaseFunds type boolean, and TransKey type string.

TransactionResponse

Contains details on the result of a processed transaction.

This object contains the results which are displayed upon successful completion of a given transaction. Includes transaction result (approved, declined, error) and authorization codes and details.

Places Used

Properties

Example Object

    usaepay.TransactionResponse response = new usaepay.TransactionResponse();

    try
    {
        response = client.runTransaction(token, tran);

        if (response.ResultCode == "A")
        {
            MessageBox.Show(string.Concat("Transaction Approved, RefNum: ",
                    response.RefNum));
        }
        else
        {
            MessageBox.Show(string.Concat("Transaction Failed: ",
                    response.Error));
        }

    usaepay.TransactionResponse response = new usaepay.TransactionResponse();

    try
    {
        response = client.runTransaction(token, tran);

        if (response.ResultCode == "A")
        {
            MessageBox.Show(string.Concat("Transaction Approved, RefNum: ",
                    response.RefNum));
        }
        else
        {
            MessageBox.Show(string.Concat("Transaction Failed: ",
                    response.Error));
        }
    }

    <Response xsi:type="ns1:TransactionResponse">
        <AcsUrl xsi:nil="true"/>
        <AuthCode xsi:type="xsd:string">021730</AuthCode>
        <AvsResult xsi:type="xsd:string">Address: Match &amp; 5 Digit Zip: Match</AvsResult>
        <AvsResultCode xsi:type="xsd:string">YYY</AvsResultCode>
        <BatchRefNum xsi:type="xsd:string">445979</BatchRefNum>
        <BatchNum xsi:type="xsd:string">979</BatchNum>
        <CardCodeResult xsi:type="xsd:string">Not Processed</CardCodeResult>
        <CardCodeResultCode xsi:type="xsd:string">P</CardCodeResultCode>
        <ConversionRate xsi:type="xsd:double">0</ConversionRate>
        <ConvertedAmount xsi:type="xsd:double">0</ConvertedAmount>
        <ConvertedAmountCurrency xsi:type="xsd:string">0</ConvertedAmountCurrency>
        <CustNum xsi:type="xsd:string">0</CustNum>
        <Error xsi:type="xsd:string">Approved</Error>
        <ErrorCode xsi:type="xsd:integer">0</ErrorCode>
        <isDuplicate xsi:type="xsd:boolean">false</isDuplicate>
        <Payload xsi:nil="true"/>
        <RefNum xsi:type="xsd:string">1175354</RefNum>
    <RefNum xsi:type="xsd:sting">1nfmkr4rsmtxhm5</TransKey>
        <Result xsi:type="xsd:string">Approved</Result>
        <ResultCode xsi:type="xsd:string">A</ResultCode>
        <Status xsi:type="xsd:string">Pending</Status>
        <StatusCode xsi:type="xsd:string">P</StatusCode>
        <VpasResultCode xsi:nil="true"/>
     </Response>

Name Type Description
TransKey string Transaction Reference Number This is the preferred Transaction Identifier (ALWAYS System Scoped)
RefNum string Transaction Reference Number (sometimes Merchant Scoped)
BatchRefNum string Batch Reference Number assigned by Gateway.
BatchKey string Batch Reference Number assigned by Gateway.
BatchNum string Batch Sequence Number
Result string Transaction Result (Approved, Declined, Error, etc)
ResultCode string Single character result code (A, D, or E)
AuthCode string Authorization Code
AuthAmount double Amount that was authorized. Could be less that Amount requested if AllowPartialAuth was true
RemainingBalance double Returns the balance remaining on some prepaid and stored value cards
AvsResultCode string AVS Result Code (1-3 characters)
AvsResult string Text Description of AvsResultCode
CardCodeResultCode string Card Code (CVV2) Verification Result Code (1 character)
CardCodeResult string Text Description of Card Code Result
CardLevelResultCode string List of codes can be found here.
CardLevelResult string Text Description of Card Level Result
%CreditCardToken% object This object describes a tokenized credit card.
ErrorCode integer Error Code (if transaction resulted in error)
CustNum string System assigned CustNum of stored customer record if one was used or created
CustKey string Customer Number (System assigned)
Error string Text Description of Error Code
AcsUrl string ACS Url for Verified by Visa or Mastercard Secure Code.
Payload string Payload for Verified by Visa or Mastercard Secure Code.
VpasResultCode string Vpas Result Code.
isDuplicate boolean If true, a duplicate transaction was detected and the response data returned is from original transaction.
ConvertedAmount double Transaction amount converted to new currency.
ConvertedAmountCurrency string Currency code for new currency.
ConversionRate double Rate used to convert transaction amount.
Status string Description of transaction status
StatusCode string Single character code for transaction status
ProfilerScore string Score generated by fraud profiler.
ProfilerResponse string Fraud profiler result: pass, warn, review. Based on score thresholds
ProfilerReason string Comma separated list of reason codes that contributed to the score.

Change Log

Version Change
1.7 Added TransKey, CustKey, and Batch Key. Changed BatchNum to type string, BatchRefNum to type string, CustNum to type string.
1.5 Added ProfilerScore, ProfilerResponse and ProfilerReason parameters
1.4 Added AuthAmount and RemainingBalance parameters
1.2 Added BatchRefNum parameter
1.1 Soap 1.1 Release (no changes)
1.0 Added Status and Status Code property

TransactionSearchResult

Contains results of a transaction search.

This object is returned by the searchTransactions method. It describes the result of the search, including the total number of transactions matched, the number being returned, and an array of TransactionObjects

Places Used

Properties

Example Object

    Dim tran As usaepay.TransactionSearchResult
            tran = New usaepay.TransactionSearchResult

            tran = client.getCustomerHistory(token, CustNum)

     usaepay.TransactionSearchResult result = new usaepay.TransactionSearchResult();

                try
                {
                    result = client.searchTransactions(token, search, matchAll, "0", "10", "created");

                    MessageBox.Show(string.Concat(result.TransactionsMatched));

                }

Name Type Description
TransactionsMatched integer Total number of transactions matched
TransactionsReturned integer Number of transactions returned in this result set
ErrorsCount integer Total number of errors matched
DeclinesCount integer Total number of declines matched
SalesCount integer Total number of Sales matched
CreditsCount integer Total number of Credits matched
AuthOnlyCount integer Total number of AuthOnlys matched
VoidsCount integer Total number of Voids matched
SalesAmount float Total dollar amount of Sales matched
CreditsAmount float Total dollar amount of Credits matched
AuthOnlyAmount float Total dollar amount of AuthOnlys matched
VoidsAmount float Total dollar amount of Voids matched
ErrorsAmount float Total dollar amount of errors matched
DeclinesAmount float Total dollar amount of Declines matched
StartIndex integer The starting index used (defaults to 0)
Limit integer The max number transactions to return in each result set.
%TransactionObject% object An array TransactionObjects for the matched transactions

TransactionSession

Transaction session data

This object contains the session data needed for transaction fraud profiling.

Places Used

Properties

Name Type Description
OrgID string Organization ID
SessionID string Unique session identifier

Boarding API v1.5

The USAePay Reseller API provides a standardized web services interface that allows resellers to leverage some of the reseller console functionality within their applications. It supports basic operations such adding new merchants to the gateway and retrieving usage reports. Since the API uses web standards, it is directly supported by many programming languages such as Dot Net and PHP.

Versioning

SOAP uses WSDL files to describe the methods and objects that are made available by a webservice. With each new version of the USAePay SOAP API a new WSDL file is released. Once a version of the API is released, it's corresponding WSDL file will not change. This allows developers to continue to use an older version of the API indefinitely without the risk of future releases breaking existing code. There is no need to upgrade to the latest version unless new functionality is desired. There is also no restriction on the number of WSDL files used by an application. Existing code can continue to use the old WSDL while newly added code can use a second WSDL link.

To obtain a wsdl for the Reseller API, please contact the Integration Support department.

Current Version: 1.5

Prior to version 1.3, the reseller api was combined with the general merchant SOAP API.

Getting Started

The following guides give specific setup instructions/background information on using Soap with some of the more common programming languages. If you are using a language not listed below, please feel free to contact us for assistance. The Soap interface can be used with any programming language that is able to communicate with an HTTPS connection.

PHP Boarding Guide

This guide provides information on using PHP with the USAePay SOAP API. The SOAP API provides an advanced interface to USAePay that allows merchants and resellers to access a wide range of functionality.

Choosing a SOAP Library

When using PHP there are several SOAP libraries available that can be used to make the integration with USAePay easier. While using a library is not required, it typically makes the development process much quicker. We've listed the two libraries that we recommend and actively support. There are several other libraries that should work well but we have not had the time to throughly test all of them.

PHP SoapClient extension

PHP 5 and above comes with a Soap extension included. USAePay recommends that all developers use this class if possible. This guide includes examples for the PHP 5 SoapClient and assumes that you have it installed correctly. To verify that you have the soap client installed run a script with:

<?php phpinfo() ?>

The output should include "Soap Client: enabled" If you do not have it installed and are using a Linux server, you will need to install the php-soap package. For example, on Red Hat EL or CentOS:

yum install php-soap

If you compile your own PHP server, include --enable-soap in the ./configure command.

If you do not have the ability to install software or recompile php, use the PEAR Soap library instead (see below).

PEAR::Soap

The official Pear repository includes a fairly full-featured Soap library written in PHP. Since it is written in PHP, it does not require any special privileges on the server. See PEAR::Soap for more information.

The information in this guide is for the PHP SoapClient extension. For information on using the PEAR::Soap library with USAePay, please see the PEAR Soap Guide.

Using SoapClient

Step 1: Instantiating $client

The first step is to instantiate the SoapClient object. In the soap example provided on this site, we use $client for this object.

    <?php       
      //for live server use 'www' for test server use 'sandbox'
      $wsdl='https://sandbox.usaepay.com/soap/resellerapi/1412E031/usaepay.wsdl';

      // instantiate SoapClient object as $client
      $client = new SoapClient($wsdl);

    ?>

If this fails with the error:

Fatal error: Cannot instantiate non-existent class: soapclient

then you do not have the SoapClient extension installed. See the directions above for more info on installing the extension.

If this fails with the error:

Unable to retrieve WSDL https://sandbox.usaepay.com/soap/resellerapi/xxxxxxxxx/usaepay.wsdl

then remove usaepay.wsdl from the link leaving only https://sandbox.usaepay.com/soap/resellerapi/1412E031/xxxxxxxx/` and try again.

Step 2: Building Security $token

Building Security $token Example

    <?php
      $sourcekey = 'R:b***********************************1';
      $pin = '1234';

      // generate random seed value
      $seed=mktime() . rand();

      // make hash value using sha1 function
      $clear= $sourcekey . $seed . $pin;
      $hash=sha1($clear);

      // assembly ueSecurityToken as an array
      $token=array(
        'SourceKey'=>$sourcekey,
        'PinHash'=>array(
           'Type'=>'sha1',
           'Seed'=>$seed,
           'HashValue'=>$hash
         ),
         'ClientIP'=>$_SERVER['REMOTE_ADDR'],
      );
    ?>

The ueSecurityToken object is used to securely identify the reseller to the gateway. To build a token, you will need the reseller's Source Key and Pin. The source key is created by the reseller in the Reseller Console under the Settings - Keys Management screen. Many of the methods in the SOAP API require the use of a PIN, and it is recommended that you always use a PIN. The reseller assigns the PIN when creating the source key.

Additional Help

For questions, please email devsupport@usaepay.com

PHP 5 (Pear) Boarding Guide

This guide provides information on using the PEAR::Soap library with the USAePay SOAP API. The SOAP API provides an advanced interface to USAePay that allows merchants and resellers to access a wide range of functionality.

The official Pear repository includes a fairly full-featured Soap library written in PHP. Since it is written in PHP, it does not require any special privileges to install on your web server. See PEAR::Soap for more information.

Using PEAR::Soap

Step 1: Including the Soap library

Including the SOAP library Example

    <?php

    require_once 'SOAP/Base.php';
    require_once 'SOAP/Client.php';

    ?>

If you have installed the PEAR::Soap library in the standard location, you should be able to use the code below. Otherwise, make sure to either add the library to your include path or provide the full path to the library files.

Step 2: Instantiating $client

Instantiating $client Example

    <?php       
      //for live server use 'www' for test server use 'sandbox'
      $wsdl='https://www.usaepay.com/soap/resellerapi/1412E031/usaepay.wsdl';

      // instantiate SOAP_Client object as $client
      $client = new SOAP_Client($wsdl);

    ?>

The first step is to instantiate the SOAP_Client object. In the soap example provided on this site, we use $client for this object.

Step 3: Building Security $token

Building Security $token Example

    <?php
      $sourcekey = 'R:b****************************************1  ';
      $pin = '1234';

      // generate random seed value
      $seed=mktime() . rand();

      // make hash value using sha1 function
      $clear= $sourcekey . $seed . $pin;
      $hash=sha1($clear);

      // assembly ueSecurityToken as an array
      $token=array(
        'SourceKey'=>$sourcekey,
        'PinHash'=>array(
           'Type'=>'sha1',
           'Seed'=>$seed,
           'HashValue'=>$hash
         ),
         'ClientIP'=>$_SERVER['REMOTE_ADDR'];
      );
    ?>

The ueSecurityToken object is used to securely identify the reseller to the gateway. To build a token, you will need the reseller's Source Key and Pin. The source key is created by the reseller in the Reseller Console under the Settings - Keys Management screen. Many of the methods in the SOAP API require the use of a PIN and it is recommended that you always use a PIN. The reseller assigns the PIN when creating the source key.

Examples

The majority of examples listed in the documentation as PHP5 will work with either the built-in Soap client, or the Pear Library. In cases where different syntax is required for the Pear library, a separate example is required.

Visual Basic Boarding Guide

Adding a Web Reference

Step 1: Generate a WSDL

For testing on sandbox you can use:

https://sandbox.usaepay.com/soap/gate/15E7FB61/usaepay.wsdl

but it is recommend that you generate your own WSDL link in the Developer's Center.

Step 2: Add WSDL to the Project in Visual Studio:

In the Solution Explorer, select the project that will be using the web service. Right-click on the project and choose Add Web Reference.

alt text

Populate the URL field with your USAePay generated WSDL link. Click Go.

alt text

Step 3: Change Web Reference name to "usaepay":

A security warning will appear, click Yes and change the Web Reference name to

usaepay

and then click Add Reference to confirm.

alt text

Once complete, you have now added a web reference called reseller to your project.

Using the Web Reference

To use the USAePay web reference, you must generate a token which authenticates your application to the gateway. This requires generating an MD5 hash value. The following steps walk through the process of creating this token. Once the token is created, running specific methods is fairly easy. For examples of a specific methods, please refer to the examples provide on each method page.

Step 1: Including Required Imports

Required Imports Example

    Imports System
    Imports System.Web
    Imports System.IO
    Imports System.Security.Cryptography
    Imports System.Text

The generation of MD5 hash requires some .NET libraries be imported into your code. Typically these import statements will go at the top of the your code.

Step 2: Instantiating the Client

Instantiating $client Example

    Dim client As New reseller.resapiService 'reseller is the name of your Web Reference

The next step is to instantiate the client object. In the soap examples provided on this site, we use the variable client for this object.

Step 3: Set a Proxy Server (if needed)

Setting a Proxy Server Example

    Dim proxycreds As New System.Net.NetworkCredential("user", "password", "Domain")
    Dim proxy As New System.Net.WebProxy("127.0.0.1", 80)

    proxy.Credentials = proxycreds
    client.Proxy = proxy

If your network requires you to use a proxy server, the next step is to reference the proxy server. If you do not have a proxy server, skip this step.

Step 4a: Building Security Token

Building Security $token Example

            Dim token As New reseller.ueSecurityToken

            token.SourceKey = "P11PON_ENTER_SOURCE_KEY_HERE_KSQr1VT81"
            token.ClientIP = "127.0.0.1"
            token.PinHash = New reseller.ueHash

            token.PinHash.Seed = "5678" 'Hard coded seed for easy troubleshooting
            token.PinHash.Type = "md5"  'Type of encryption

            Dim prehashvalue As String
            prehashvalue = token.SourceKey & token.PinHash.Seed & "1234" 'Put together the pieces

            token.PinHash.HashValue = Me.GenerateHash(prehashvalue) 'Pass the prehashvalue to a GenerateHash function

The ueSecurityToken object is used to securely identify the reseller to the gateway. To build a token, you will need the reseller's Source Key and Pin. The source key is created by the reseller in the Reseller Console under the Settings - Keys Management screen. Many of the methods in the SOAP API require the use of a PIN, and it is recommended that you always use a PIN. The reseller assigns the PIN when creating the source key.

Step 4b: Generating a Hash

Generate Hash Example

    Private Function GenerateHash(ByVal SourceText As String) As String
            'Instantiate an MD5 Provider object
            Dim md5 As New MD5CryptoServiceProvider

            'Compute the hash value from the source
            Dim ByteHash() As Byte = md5.ComputeHash(Encoding.Default.GetBytes(SourceText))

            'Instantiate a StringBuilder object
            Dim sb As New StringBuilder

            'Repack binary hash as hex
            For c As Integer = 0 To ByteHash.Length - 1
                sb.AppendFormat("{0:x2}", ByteHash(c))
            Next c

            'Return the hex hash
            Return sb.ToString
        End Function

The above code expects a GenerateHash method to be present in your class. Copy and paste the function below into your class.

Handling Events

Example Code

    Private WithEvents client As reseller.usaepayService

    Private Sub handleStatusUpdate(ByVal sender, ByVal ev As reseller.addMerchantApplicationCompletedEventArgs) Handles client.addMerchantApplicationCompleted

       MsgBox("Application added!")

    End Sub

The visual studio webservice implementation allows you to subscribe to a "completed" event that will be raised when a soap call completes. The following code demonstrates how to subscribe to the addMerchantApplicationCompleted event:

Visual Basic 2010 Boarding Guide

Adding a Web Reference

Step 1: Generate a WSDL

For testing on sandbox you can use

https://sandbox.usaepay.com/soap/resellerapi/1412E031/usaepay.wsdll

but it is recommend that you generate your own wsdl link in the Developer Portal.

Step 2: Add WSDL to the Project in Visual Studio:

In the Solution Explorer, select the project that will be using the USAePay service. Right-click on the project and choose Add Service Reference and a dialog box will open.

alt text

Populate the URL field with your USAePay generated WSDL link. Click Go.

alt text

Step 3: Change Service Reference name to "reseller":

Change the namespace to:

reseller

Then click OK to confirm

alt text

Once complete, you have now added a service reference called reseller to your project.

Using the Web Service Reference

To use the USAePay web reference, you must generate a "token" which authenticates your application to the gateway. This requires generating an MD5 hash value. The following steps walk through the process of creating this token. Once the token is created, running specific methods is fairly easy. For examples of specific methods, please refer to the examples provided on each method's page.

Step 1: Including Required Imports

Required Imports Example

    Imports System
    Imports System.Web
    Imports System.IO
    Imports System.Security.Cryptography
    Imports System.Text

The generation of an MD5 hash value requires that you import some .NET libraries into your code. Typically these import statements will go at the top of the your code.

Step 2: Instantiating the Client

Instantiating $client Example

    Dim client As New reseller.ueSoapServerPortTypeClient 'reseller' is the name of your Web Reference

The next step is to instantiate the client object. In the soap examples provided on this site, we use the variable "client" for this object.

Step 3: Setting a Proxy Server (if needed)

Setting a Proxy Server Example

    Dim proxycreds As New System.Net.NetworkCredential("user", "password", "Domain")
    Dim proxy As New System.Net.WebProxy("127.0.0.1", 80)

    proxy.Credentials = proxycreds
    client.Proxy = proxy

If your network requires you to use a proxy server, the next step is to reference the proxy server. If you do not have a proxy server, skip this step.

Step 4a: Building Security Token

Building Security $token Example

            Dim token As New reseller.ueSecurityToken

            token.SourceKey = "P11PON_ENTER_SOURCE_KEY_HERE_KSQr1VT81"
            token.ClientIP = "127.0.0.1"
            token.PinHash = New reseller.ueHash

            token.PinHash.Seed = "5678" 'Hard coded seed for easy troubleshooting
            token.PinHash.Type = "md5"  'Type of encryption

            Dim prehashvalue As String
            prehashvalue = token.SourceKey & token.PinHash.Seed & "1234" 'Put together the pieces

            token.PinHash.HashValue = Me.GenerateHash(prehashvalue) 'Pass the prehashvalue to a GenerateHash function

The ueSecurityToken object is used to securely identify the reseller to the gateway. To build a token, you will need the reseller's Source Key and Pin. The source key is created by the reseller in the Reseller Console under the Settings - Keys Management screen. Many of the methods in the SOAP API require the use of a PIN, and it is recommended that you always use a PIN. The reseller assigns the PIN when creating the source key.

Step 4b: Generating a Hash

Generate Hash Example

    Private Function GenerateHash(ByVal SourceText As String) As String
            'Instantiate an MD5 Provider object
            Dim md5 As New MD5CryptoServiceProvider

            'Compute the hash value from the source
            Dim ByteHash() As Byte = md5.ComputeHash(Encoding.Default.GetBytes(SourceText))

            'Instantiate a StringBuilder object
            Dim sb As New StringBuilder

            'Repack binary hash as hex
            For c As Integer = 0 To ByteHash.Length - 1
                sb.AppendFormat("{0:x2}", ByteHash(c))
            Next c

            'Return the hex hash
            Return sb.ToString
        End Function

The above code expects a "GenerateHash" method to be present in your class. Copy and paste the function below into your class.

Handling Events

Example Code

    Private WithEvents client As reseller.usaepayService

    Private Sub handleStatusUpdate(ByVal sender, ByVal ev As usaepay.addMerchantApplicationEventArgs) Handles client.addMerchantApplicationCompleted

       MsgBox("Application added!")

    End Sub

The visual studio webservice implementation allows you to subscribe to a "completed" event that will be raised when a soap call completes. The following code demonstrates how to subscribe to the addMerchantApplicationCompleted event:

C# Boarding Guide

Adding a Web Reference

Step 1: Generate a WSDL

For testing on sandbox you can use:

https://sandbox.usaepay.com/soap/resellerapi/1412E031/usaepay.wsdl

but it is recommend that you generate your own wsdl link in the Developer Portal

Step 2: Add WSDL to the Project in Visual Studio:

In the Solution Explorer, select the project that will be using the web service. Right-click on the project and choose Add Web Reference and a dialog box will open.

alt text

Populate the URL field with your USAePay generated WSDL link. Click Go.

alt text

A security warning will appear, click Yes and change the Web Reference name to:

reseller

Then click Add Reference to confirm.

alt text

Once complete, you have now added a web reference called reseller to your project.

Using the Web Reference

To use the USAePay web reference, you must generate a "token" which authenticates your application to the gateway. This requires generating an MD5 hash value. The following steps walk through the process of creating this token. Once the token is created, running specific methods is fairly easy. For examples of a specific methods, please refer to the examples provide on each method page.

Step 1: Including Required Headers

Required Headers Example

    using System;
    using System.Web;
    using System.Security.Cryptography;
    using System.Text;

The generation of MD5 hash requires some .NET libraries be imported into your code. Typically these using statements will go at the top of the your code.

Step 2: Instantiating the client

Instantiating $client Example

    reseller.usaepayService client = new usaepayService();  //reseller is the name of your Web Reference

The next step is to instantiate the client object. In the soap examples provided on this site, we use the variable 'client' for this object.

Step 3: Set a Proxy Server (if needed)

Setting a Proxy Server Example

    System.Net.NetworkCredential proxycreds = new System.Net.NetworkCredential("user", "password");
    System.Net.WebProxy proxy = new System.Net.WebProxy("127.0.0.1", 80); //address of proxy server
    proxy.Credentials = proxycreds;
    client.Proxy = proxy;

If your network requires you to use a proxy server, the next step is to reference the proxy server. If you do not have a proxy server, skip this step.

Step 4a: Building Security Token

Building Security $token Example

    reseller.ueSecurityToken token = new reseller.ueSecurityToken();

    token.SourceKey = "P11PON_ENTER_SOURCE_KEY_HERE_KSQr1VT81";
    token.ClientIP = "11.22.33.44";  // IP address of end user (if applicable)
    string pin = "1234";   // pin assigned to source

    reseller.ueHash hash = new reseller.ueHash();
    hash.Type = "md5";  // Type of encryption
    hash.Seed = Guid.NewGuid().ToString();  // unique encryption seed

    string prehashvalue = string.Concat(token.SourceKey, hash.Seed, pin);  // combine data into single string
    hash.HashValue = GenerateHash(prehashvalue); // generate hash

    token.PinHash = hash;   // add hash value to token

The ueSecurityToken object is used to securely identify the reseller to the gateway. To build a token, you will need the reseller's Source Key and Pin. The source key is created by the reseller in the Reseller Console under the Settings - Keys Management screen. Many of the methods in the SOAP API require the use of a PIN, and it is recommended that you always use a PIN. The reseller assigns the PIN when creating the source key.

Step 4b: Generating a Hash

Generate Hash Example

           private static string GenerateHash(string input)
            {
                // Create a new instance of the MD5CryptoServiceProvider object.
                MD5 md5Hasher = MD5.Create();

                // Convert the input string to a byte array and compute the hash.
                byte[] data = md5Hasher.ComputeHash(Encoding.Default.GetBytes(input));

                // Create a new Stringbuilder to collect the bytes
                // and create a string.
                StringBuilder sBuilder = new StringBuilder();

                // Loop through each byte of the hashed data
                // and format each one as a hexadecimal string.
                for (int i = 0; i < data.Length; i++)
                {
                    sBuilder.Append(data[i].ToString("x2"));
                }

                // Return the hexadecimal string.
                return sBuilder.ToString();
            }

The above code expects a "GenerateHash" method to be present in your class. Copy and paste the function below into your class.

Step 5: Calling Soap Method

Call Method Example Code

    string merchantID = "133534";
    reseller.Merchant merchant = new reseller.Merchant();

    try
    {
       merchant = reclient.getMerchant(retoken, merchantID);
       MessageBox.Show(string.Concat(merchant.MerchantName));
    }
    catch (Exception err) {
       MessageBox.Show(err.Message);
    }

Now that you have a security token created you can make calls to the soap methods listed in the api. For example, to close the currently open credit credit card batch:

JavaJAX-WS Boarding Guide

The following guide demonstrates how to use the USAePayResApi-jaxws.jar package with either Sun's Jax-WS 2.1 or Apache Foundation's CXF libary. This package contains a helper class for easily generating security tokens, classes for all USAePay objects and a client service class for calling web service methods. The package requires Jax-WS (see Dependencies).

Downloads

File Version Release Date Description
usaepayresapi-jaxws-1.4.0.zip 1.4.0 10/07/10 Library .jar and example .java
usaepayresapi-jaxws-1.4.0.zip 1.4.0 10/07/10 USAePayResAPI-jaxws-1.4.jar only

Dependencies (Using Apache CXF)

Dependencies (Using Sun's Jax-WS 2.1)

Using Library

Step 1: Import Classes

Import Classes Example

    import com.usaepay.resapi.jaxws.*;

In classes that are going to use the USAePay methods or object, you need to import the appropriate classes from com.usaepay.resapi.jaxws package. The following will import all usaepay objects at once:

Step 2a: Instantiating the Client

Instantiating $client Example

    // Instantiate client for production
    UeSoapServerPortType client = usaepay.getClient();

All calls to the USAePay web service are handled by a client object of type UeSoapServerPortType. There are two ways to instantiate the client object. To instantiate a client for use with the main production servers use this example.

Step 2b: Specify Server

Specify Server Example

    // Instantiate client for sandbox
    UeSoapServerPortType client = usaepay.getClient("sandbox.usaepay.com");

Alternately, you can specify a server hostname, which will allow you to setup a connection to the sandbox server for testing or a backup datacenter (see the high availability programming guide).

Step 3: Building Security Token

Building Security $token Example

    // Create security token
    String SourceKey="YourKeyGoesHere";
    String Pin ="YourPinGoesHere";
    String ClientIP="10.10.10.10";
    UeSecurityToken restoken = usaepay.getToken(SourceKey, Pin, ClientIP);

A restoken object (of type UeSecurityToken) is required by all methods in the USAePay Reseller API. It is used to identify and authenticate the reseller.

Step 4: Calling a SOAP Method

Call Method Example Code

    // Set the merchant ref num (merchid)
    BigInteger merchrefnum = new BigInteger("118227");

    // Create response object
    Merchant merch;

    // Retrieve Merchant
    merch = client.getMerchant(restoken, merchrefnum);

    // Display response
    System.out.println("Merchant: " + merch.getMerchantName());

Web service methods are called using the client object. This is an example for calling the getMerchant method. For further examples see the api documentation.

Boarding Methods

Merchant Application Methods

addMerchantApplication

Example Request

    <?php

    try {

      $App=new stdClass();

      $App->ResellerEmail='applications@reseller.com';

      $App->ContactInfo = new stdClass();
      $App->MerchantName = "Acme Bagel Company";
      $App->ContactInfo->Contact = "John Doe"; 
      $App->ContactInfo->Street  ='4929 Wilshire Blvd';
      $App->ContactInfo->Street2 ='Suite 800';
      $App->ContactInfo->City    ='Los Angeles'; 
      $App->ContactInfo->State   ='CA';            
      $App->ContactInfo->Zip     ='90010';           
      $App->ContactInfo->Country ='US';        
      $App->ContactInfo->Email   = 'john@acme';
      $App->ContactInfo->Fax         ='012134567890';      
      $App->ContactInfo->Phone   ='687668678677';     
      $App->ContactInfo->MobilePhone='798787978788';
      $App->ContactInfo->AltEmail='mary@acmebagels.com';
      $App->ContactInfo->URL = 'http://acme bagels.com';

      $App->BillingInfo = new stdClass();
      $App->BillingInfo->BankName = 'Bank of America';
      $App->BillingInfo->RoutingNumber = '12342313312';
      $App->BillingInfo->AccountNumber = '57655765754';
      $App->BillingInfo->GatewayPackage = 'Platinum Package';

      $App->CreditCardPlatform = 'FDMS';
      $App->CreditCardIndustry = 'Retail';
      $App->CreditCardPlatformSetup = array();
      $App->CreditCardPlatformSetup[] = array('Field'=>'MerchantNum', 'Value'=>'4454900399430020');
      $App->CreditCardPlatformSetup[] = array('Field'=>'MerchantID', 'Value'=>'382772891');
      $App->CreditCardPlatformSetup[] = array('Field'=>'TerminalID', 'Value'=>'112198000');

      $App->eCheckPlatform = 'Vericheck';
      $App->eCheckPlatformSetup = array();
      $App->eCheckPlatformSetup[] = array('Field'=>'DefaultSEC', 'Value'=>'TEL');
      $App->eCheckPlatformSetup[] = array('Field'=>'TaxID', 'Value'=>'123456789');
      $App->eCheckPlatformSetup[] = array('Field'=>'PIN', 'Value'=>'231');
      $App->eCheckPlatformSetup[] = array('Field'=>'MID', 'Value'=>'11231');
      $App->eCheckPlatformSetup[] = array('Field'=>'AcceptedSecCodes', 'Value'=>'TEL,PPD,CCD');

      $App->SourceKeyName = 'My Shopping Cart';
      $App->SourceKeyPin = '1351';
      $App->EmailSourceKeyTo = 'demo@acmebagels.com';

      $App->UserName = 'acmebagels';
      $App->EmailInstructionsTo = 'demo@acmebagels.com';

      $App->ApplicationNotes = 'An example note for merchant application';

      $ApplicationID=$client->addMerchantApplication($restoken, $App);
                            
    } 

    catch (SoapFault $e) {
      echo $client->__getLastRequest();
      echo $client->__getLastResponse();
      die("addMerchantApplication failed: " .$e->getMessage());
    }

    ?>  
       
                reseller.MerchantApplication merchant = new reseller.MerchantApplication();
                merchant.ResellerEmail = "irina@usaepay.com";
                merchant.MerchantName = "Acme Bagel Company";
                merchant.ContactInfo = new reseller.ContactInfo();
                merchant.ContactInfo.Contact = "Tester Jones";
                merchant.ContactInfo.Street = "123 main st.";
                merchant.ContactInfo.Street2 = "suit 100";
                merchant.ContactInfo.City = "Los Angeles";
                merchant.ContactInfo.State = "CA";
                merchant.ContactInfo.Zip = "90038";
                merchant.ContactInfo.Country = "USA";
                merchant.ContactInfo.Email = "irina@usaepay.com";
                merchant.ContactInfo.Fax = "800-888-9999";
                merchant.ContactInfo.Phone = "800-888-9999";
                merchant.ContactInfo.MobilePhone = "800-999-8888";
                merchant.ContactInfo.AltEmail = "irina@usaepay.com";
                merchant.ContactInfo.URL = "http://test.com";
                merchant.BillingInfo = new reseller.BillingInfo();
                merchant.BillingInfo.BankName = "Bank of America";
                merchant.BillingInfo.RoutingNumber = "123456789";
                merchant.BillingInfo.AccountNumber = "123456789";
                merchant.BillingInfo.GatewayPackage = "Platinum Package";

                merchant.CreditCardPlatform = "FDMS";
                merchant.CreditCardIndustry = "Retail (Swipe)";
                reseller.FieldValue[] platform = new reseller.FieldValue[3];
                for (int i = 0; i < 3; i++){
                    platform[i] = new reseller.FieldValue();
                }
                platform[0].Field = "MerchantNum"; platform[0].Value = "4454900399430020";
                platform[1].Field = "MerchantID";  platform[1].Value = "382772891";
                platform[2].Field = "TerminalID"; platform[2].Value = "382772891";

                merchant.CreditCardPlatformSetup = platform;

                merchant.eCheckPlatform = "Vericheck";
                reseller.FieldValue[] checkplatform = new reseller.FieldValue[5];
                for (int i = 0; i< 5; i++){
                    checkplatform[i] = new reseller.FieldValue();
                }

                checkplatform[0].Field = "DefaultSEC"; checkplatform[0].Value = "TEL";
                checkplatform[1].Field = "TaxID"; checkplatform[1].Value = "123456789";
                checkplatform[2].Field = "PIN"; checkplatform[2].Value = "231";
                checkplatform[3].Field = "MID"; checkplatform[3].Value = "11231";
                checkplatform[4].Field = "AcceptedSecCodes"; checkplatform[4].Value = "TEL,PPD,CCD";

                merchant.eCheckPlatformSetup = checkplatform;

                merchant.SourceKeyName = "My Shopping Cart";
                merchant.SourceKeyPin = "1351";
                merchant.EmailInstructionsTo = "test@test.com";

                merchant.UserName = "testmerchant";
                merchant.EmailSourceKeyTo = "test@test.com";

                merchant.ApplicationNotes = "an example";

                string refNum;

                try
                {
                    refNum = reclient.addMerchantApplication(retoken,merchant);
                    MessageBox.Show(string.Concat(refNum));
                }


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

               MerchantApplication merchantapp = new MerchantApplication();


                merchantapp.setApplicationNotes("Application notes");

                BillingInfo billing = new BillingInfo();
                billing.setBankName("Example Bank");
                billing.setRoutingNumber("123456789");
                billing.setAccountNumber("910293112");
                billing.setGatewayPackage("Silver Package");
                merchantapp.setBillingInfo(billing);

                merchantapp.setCallInPassword("1234");
                ContactInfo contactinfo = new ContactInfo();
                contactinfo.setContact("John Doe");
                contactinfo.setStreet("4929 Wilshire Blvd");
                contactinfo.setStreet2("Suite 899");
                contactinfo.setCity("Los Angeles");
                contactinfo.setState("CA");
                contactinfo.setZip("90010");
                contactinfo.setCountry("US");
                contactinfo.setEmail("merchant@tmcode.com");
                contactinfo.setAltEmail("merchant@tmcode.com");
                contactinfo.setPhone("222-333-4446");
                contactinfo.setMobilePhone("222-333-4445");
                contactinfo.setFax("222-333-4444");
                contactinfo.setURL("http://www.acme.org");
                merchantapp.setContactInfo(contactinfo);

                merchantapp.setCreditCardIndustry("eCommerce");
                merchantapp.setCreditCardPlatform("FDMS");

                FieldValueArray platformdata = new FieldValueArray();
                platformdata.add(new FieldValue("MerchantNum","2334566356345"));
                platformdata.add(new FieldValue("MerchantID","1231230"));
                platformdata.add(new FieldValue("TerminalID","1231239"));
                merchantapp.setCreditCardPlatformSetup(platformdata);

                merchantapp.setECheckPlatform("Vericheck");
                FieldValueArray checkplatform = new FieldValueArray();
                checkplatform.add(new FieldValue("DefaultSEC","TEL"));
                checkplatform.add(new FieldValue("TaxID","123456789"));
                checkplatform.add(new FieldValue("PIN","231"));
                checkplatform.add(new FieldValue("MID","11231"));
                checkplatform.add(new FieldValue("AcceptedSecCodes","TEL,PPD,CCD"));
                merchantapp.setECheckPlatformSetup(checkplatform);

                merchantapp.setEmailInstructionsTo("merchant@tmcode.com");
                merchantapp.setEmailSourceKeyTo("merchant@tmcode.com");
                merchantapp.setMerchantName("Example Company");
                merchantapp.setResellerEmail("reselller@tmcode.com");
                merchantapp.setSourceKeyName("ShoppingCart");
                merchantapp.setSourceKeyPin("1234");
                merchantapp.setUserName("jdoe23");


                BigInteger apprefnum;

                apprefnum = client.addMerchantApplication(restoken, merchantapp);

Reseller Only Method

This method adds a new merchant application to the system. If successful, the application ID will be returned. The application ID can be used to check on the status of the merchant application.

Please note that this function does not create a merchant account. The application will be reviewed and activated by the gateway staff. Once activated, a merchant ID will be assigned and all supported merchant related methods may be used.

Related Methods

Syntax

integer addMerchantApplication ( ueSecurityToken Token, MerchantApplication Application )

Request Parameters

Name Type Description
%ueSecurityToken% object Reseller security token: used to identify reseller and validate request.
%MerchantApplication% object MerchantApplication object containing merchant information.

Response Parameters

Name Type Description
ApplicationID integer Returns merchant application ID if successful, if request fails, an exception will be thrown.

Exceptions

Code Message Advice
19000 Unable to save application. A temporary error occurred while saving the application. Try again or contact support
19001 The field 'fieldname' is required. A required field was not populated. See the error message for the name of the missing field.
19014 Email address 'fieldname' not valid The email address fields was not a valid email address. It did not pass the formatting check. Check formatting.
19015 Email address 'fieldname' not valid One of the email addresses entered was invalid. It did not pass the DNS or mail server delivery checks. Double check the address.
19016 Requested credit card platform not supported The CreditCardPlatform was not found in the list of supported platforms
19017 Requested credit card industry not supported The CreditCardIndustry was not a supported industry.
19019 Requested check platform not supported The eCheckPlatform was not found in the list of supported platforms.
19020 Billing package not found. Specified billing package was not found. Double check the list of valid billing package names.

Change Log

Version Change
1.1 Method added prior to soap-1.1

getMerchantApplication

Example Request

    <?php

    try { 

      $ApplicationID = 2; 

      $Application=$client->getMerchantApplication($restoken, $ApplicationID); 

      print_r($Application);  
                             
    } 

    catch (SoapFault $e) { 

      echo $client->__getLastRequest(); 
      echo $client->__getLastResponse(); 
      die("getMerchantApplication failed: " .$e->getMessage()); 
      } 

    ?> 

    string appID = "10943080";
                reseller.MerchantApplication result = new reseller.MerchantApplication();

                try
                {
                    result = reclient.getMerchantApplication(retoken, appID);
                    MessageBox.Show(string.Concat(result.ContactInfo.Contact));
                }
                catch (Exception err) {
                    MessageBox.Show(err.Message);
                }

    BigInteger apprefnum = new BigInteger("865");
    MerchantApplication merchapp;
    merchapp = client.getMerchantApplication(restoken, apprefnum);

Reseller Only Method

This method pulls the application for a pending merchant.  Requires the gateway assigned ApplicationID. Returns a MerchantApplication object containing application information. 

Related Methods

Syntax

MerchantApplication getMerchantApplication ( ueSecurityToken Token, integer ApplicationID ) 

Request Parameters

Name Type Description
%ueSecurityToken% object Reseller security token, used to identify reseller and validate request.
ApplicationID integer Application ID number assigned by the gateway

Response Parameters

Name Type Description
%MerchantApplication% object Returns merchant application object

getMerchantApplicationStatus

Example Request

    <?php

    try {

      $ApplicationID=2;

      $Status=$resclient->getMerchantApplicationStatus($restoken, $ApplicationID);

    }

    catch (SoapFault $e) {

      echo $client->__getLastRequest();
      echo $client->__getLastResponse();
      die("getMerchantApplicationStatus failed: " .$e->getMessage());

    }

    ?>

    BigInteger apprefnum = new BigInteger("865");
    String appstatus;
    appstatus = client.getMerchantApplicationStatus(restoken, apprefnum);

Reseller Only Method

This method returns the status of a merchant application (added either via the reseller console or the addMerchantApplication method). The application ID that was obtained when adding the merchant application must be passed.

Possible values for status include: * Pending - Application pending review * Under Review - Application is in the process of being reviewed * Waiting For Documents - Additional documents needed * Call Support - Application on hold, call for details * Declined - Application was declined * Approved - Merchant activated * Canceled - Application canceled

Related Methods

Syntax

string getMerchantApplicationStatus ( ueSecurityToken Token, integer ApplicationID )

Request Parameters

Name Type Description
%ueSecurityToken% object Reseller security token, used to identify reseller and validate request.
ApplicationID integer The merchant application number assigned by the gateway.

Response Parameters

Name Type Description
getMerchantApplicationStatusReturn string Returns merchant application status. Possible results include: pending, under review, waiting for documents, on hold, declined, activated, canceled.

Merchant Methods

getMerchant

Example Request

    <?php

    try { 

      $MerchRefNum=2; 

      $Merchant=$client->getMerchant($restoken, $MerchRefNum); 

      print_r($Merchant);  
                             
    } 

    catch (SoapFault $e) { 

      echo $client->__getLastRequest(); 
      echo $client->__getLastResponse(); 
      die("getMerchant failed: " .$e->getMessage()); 
      } 

    ?> 

    string merchantID = "133534";
    reseller.Merchant merchant = new reseller.Merchant();

    try
    {
       merchant = reclient.getMerchant(retoken, merchantID);
       MessageBox.Show(string.Concat(merchant.MerchantName));
    }
    catch (Exception err) {
       MessageBox.Show(err.Message);
    }

    BigInteger merchrefnum = new BigInteger("118227");
    Merchant merchant;
    merchant = client.getMerchant(restoken, merchrefnum);

Reseller only method

This method pulls the account information for an active merchant.  Requires the gateway assigned MerchantID. Returns a Merchant object containing merchant's contact, billing and platform information. The account number and the routing number for the billing information is masked.

Related Methods

Syntax

Merchant getMerchant ( ueSecurityToken Token, integer MerchantID ) 

Request Parameters

Name Type Description
%ueSecurityToken% object Reseller security token, used to identify reseller and validate request.
MerchRefNum integer Merchant ID number assigned by the gateway to an active merchant

Response Parameters

Name Type Description
%Merchant% object Returns merchant object

updateMerchant

Example Request

    <?php

    try {

      $objMerchant=new MerchantObject();
      $MerchRefNum='2';
      print_r($objMerchant);

      $res=$client->updateMerchant($restoken,$MerchRefNum,$objMerchant);
      print_r($res);     


      }

    catch (SoapFault $e) {
      echo $client->__getLastRequest();
      echo $client->__getLastResponse();
      die("updateMerchant failed: " .$e->getMessage());
    }

    ?>

    string merchantID = "133534";

                reseller.Merchant merchant = new reseller.Merchant();
                merchant.MerchantName = "Another company";

                Boolean response;
                try
                {
                    response = reclient.updateMerchant(retoken, merchantID, merchant);
                    MessageBox.Show(string.Concat(response));
                }
                catch (Exception err) {
                    MessageBox.Show(err.Message);
                }

                BigInteger merchrefum = new BigInteger("117821");

                Merchant merchchange = new Merchant();

                merchchange.setMerchantName("New Company Name");
                ContactInfo contactinfo = new ContactInfo();
                contactinfo.setContact("John Doe");
                contactinfo.setStreet("1234 Main");
                contactinfo.setStreet2("Suite 800");
                contactinfo.setCity("Los Angeles");
                contactinfo.setState("CA");
                contactinfo.setZip("11221");
                contactinfo.setCountry("US");
                contactinfo.setEmail("tim@tmcode.com");
                contactinfo.setPhone("223-222-1121");
                contactinfo.setFax("590-223-9902");
                merchchange.setContactInfo(contactinfo);

                client.updateMerchant(restoken, merchrefum, merchchange);

Reseller only method

Allows a reseller to update the information on file for a merchant account.

The following fields may be updated via this method:

Related Methods

Syntax

boolean updateMerchant ( ueSecurityToken Token, integer MerchRefNum, Merchant Merchant )

Request Parameters

Name Type Description
%ueSecurityToken% object Reseller security token, used to identify reseller and validate request.
MerchRefNum integer Merchant ID number assigned by the gateway to an active merchant.
%Merchant% object Merchant account information including: ID, Company, Contact, Address, Email, Phone, and Fax.

Response Parameters

Name Type Description
updateMerchantReturn boolean Returns confirmation of update only if successful. If update fails, an exception will be thrown.

deleteMerchant

Example Request

    <?php

    try {

      $MerchRefNum=2;
      $Reason='Testing Soap API';     

      $client->deleteMerchant($restoken,$MerchRefNum,$Reason);

    }

    catch (SoapFault $e) {
      echo $client->__getLastRequest();
      echo $client->__getLastResponse();
    }

    ?>

    BigInteger merchrefnum = new BigInteger("118227");
    boolean res = client.deleteMerchant(restoken, merchrefnum, "Merchant is no longer active");

Reseller Only Method

This method will flag a merchant for deletion. Once the deletion request is verified and approved by the gateway, the merchant account will be closed and the merchant will no longer be able to process transactions or log in to the Merchant Console.

The reason argument should include any details, such as contact request details, reason for deletion, etc. that may speed up the deletion request verification process.

Related Methods

Syntax

boolean deleteMerchant ( ueSecurityToken Token, integer MerchRefNum, string Reason )

Request Parameters

Name Type Description
%ueSecurityToken% object Reseller security token, used to identify reseller and validate request.
MerchRefNum integer Merchant ID number assigned by the gateway to an active merchant
Reason string Any information relevant to the delete merchant account request. You may wish to include the following: contact request details, reason for deletion request, any other relevant information.

Response Parameters

Name Type Description
deleteMerchantReturn boolean Returns confirmation of your request only if successful. If request fails, an exception will be thrown.

Exceptions

Code Message Advice
19003 Requested merchant not found. The MerchRefNum did not match a merchant account associated with your reseller account. Double check MerchRefNum.
19005 Requested merchant was deleted and is no longer active. The merchant account was already deleted. Double check the MerchRefNum and make sure the delete call is only running once.

Merchant Search Methods

searchMerchants

Example Request

    <?php

    try {
      $search=array(
        array('Field'=>'State', 'Type'=>'eq','Value'=>'CA'),
        array('Field'=>'Contact', 'Type'=>'eq', 'Value'=>'John Doe'),
        array('Field'=>'Company', 'Type'=>'eq', 'Value'=>'DidorightInc.')
      );
      $start=0;
      $limit=100;
      $matchall=true;
      $sortby='merchid';

      $res=$client->searchMerchants($restoken,$search,$matchall,$start,$limit, $sortby);

    }

    catch (SoapFault $e) {
      echo $client->__getLastRequest();
      echo $client->__getLastResponse();
      die("searchMerchants failed: " .$e->getMessage());
      }

    ?>

    SearchParamArray params = new SearchParamArray();
    params.add(new SearchParam("State", "eq", "CA"));

    MerchantSearchResult result;
    result = client.searchMerchants(restoken, params, true, BigInteger.ZERO, new BigInteger("100"), "MerchRefNum");

    System.out.println("Found Merchant: " + result.getMerchants().getMerchants().get(1).getMerchantName());

Reseller only method.

This method allows resellers to search their database for active merchants based on specific criteria.

The following fields may be searched via this method:

If MatchAll is set to "true," then only results matching ALL of your search criteria will be returned. If your search does not yield the desired results, eliminate some of you search terms or set MatchAll to "false."

Related Methods

Syntax

MerchantSearchResult searchMerchants ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string Sort)

Request Parameters

Name Type Description
%ueSecurityToken% object Reseller security token, used to identify reseller and validate request.
%SearchParam% array Array of search parameters.
MatchAll boolean If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned.
Start integer Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200)
Limit integer Maximum number of records to return in result set.
Sort string Comma separated list of fields to sort by.

Response Parameters

Name Type Description
%MerchantSearchResult% Returns results of active merchant search based on search parameters set.

Change History

Version Change
1.2 Added Sort Parameter
1.1 Soap 1.1 Release

searchMerchantsCount

Example Request

    <?php

    try {
      $search=array(
        array('Field'=>'State', 'Type'=>'eq','Value'=>'CA'),
        array('Field'=>'Contact', 'Type'=>'eq', 'Value'=>'John Doe'),
        array('Field'=>'Company', 'Type'=>'eq', 'Value'=>'DidorightInc.')
      );
      $start=0;
      $limit=100;
      $matchall=true;
      $sortby='merchid';

      $res=$client->searchMerchantsCount($restoken,$search,$matchall,$start,$limit, $sortby);
      print_r($res);
    }

    catch (SoapFault $e) {
      echo $client->__getLastRequest();
      echo $client->__getLastResponse();
      die("searchMerchants failed: " .$e->getMessage());
    }

    ?>

    SearchParamArray params = new SearchParamArray();
    params.add(new SearchParam("State", "eq", "CA"));

    MerchantSearchResult result;
    result = client.searchMerchantsCount(restoken, params, true, BigInteger.ZERO, new BigInteger("100"), "MerchRefNum");

Reseller only method

Identical to the searchMerchants method except only the merchants counts are returned. Like searchMerchants, this method returns MerchantSearchResult. The only difference is that MerchantSearchResult.Merchants is left empty. This method provides a quicker way to determine the size of the result set before starting to retrieve the full search results.

Related Methods

Syntax

MerchantSearchResult searchMerchantsCount ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string Sort)

Request Parameters

Name Type Description
%ueSecurityToken% object Reseller security token, used to identify reseller and validate request.
%SearchParam% array Array of search parameters.
MatchAll boolean If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned.
Start integer Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200)
Limit integer Maximum number of records to return in result set.
Sort string Comma separated list of fields to sort by.

Response Parameters

Name Type Description
%MerchantSearchResult% Returns results of active merchant search based on search parameters set.

Change History

Version Change
1.2 Method added in soap 1.2 release

searchMerchantsCustom

Reseller only method

Use this method if you only need to view a few select fields of the merchants you are searching for. Since it will only return the fields you specify, it is more efficient than the searchMerchants method.

Related Methods

The following fields may be used to search the database for transactions:

Syntax

string searchMerchants ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string FieldList, string Format, string Sort)

Request Parameters

Name Type Description
%ueSecurityToken% object Reseller security token, used to identify reseller and validate request.
%SearchParam% array Array of search parameters.
MatchAll boolean If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned.
Start integer Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200)
Limit integer Maximum number of records to return in result set.
Sort string Comma separated list of fields to sort by.
FieldList list List of fields to return in search.
Format string Specify format of return data. Possible formats include: csv, tab, xml.

Response Parameters

Name Type Description
searchMerchantsCustomReturn string Base64 encode result set. Returns all of the fields from any merchants matching your search parameters.

Change History

Version Change
1.2 Method added in soap 1.2 release

searchMerchantApplications

Example Request

    <?php

    try {
      $search=array(
        array('Field'=>'State', 'Type'=>'eq','Value'=>'CA'),
        array('Field'=>'Contact', 'Type'=>'eq', 'Value'=>'John Doe'),
        array('Field'=>'Company', 'Type'=>'eq', 'Value'=>'DidorightInc.')
      );
      $start=0;
      $limit=100;
      $matchall=true;
      $sortby='merchid';

      $res=$client->searchMerchantApplications($restoken,$search,$matchall,$start,$limit, $sortby);

    }

    catch (SoapFault $e) {
      echo $client->__getLastRequest();
      echo $client->__getLastResponse();
      die("searchMerchantApplications failed: " .$e->getMessage());
      }

    ?>

    SearchParamArray params = new SearchParamArray();
    params.add(new SearchParam("State", "eq", "CA"));

    MerchantApplicationSearchResult result;
    result = client.searchMerchantApplications(restoken, params, true, BigInteger.ZERO, new BigInteger("100"), "MerchRefNum");

    System.out.println("Found Merchant: " + result.getApplications().getMerchantApplications().get(1).getMerchantName());

Reseller only method

This method allows resellers to search their database for merchant applications based on specific criteria.

The following fields may be searched via this method:

If MatchAll is set to "true," then only results matching ALL of your search criteria will be returned. If your search does not yield the desired results, eliminate some of you search terms or set MatchAll to "false."

Related Methods

Syntax

MerchantApplicationSearchResult searchMerchantApplications ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string Sort)

Request Parameters

Name Type Description
%ueSecurityToken% object Reseller security token, used to identify reseller and validate request.
%SearchParam% array Array of search parameters.
MatchAll boolean If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned.
Start integer Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200)
Limit integer Maximum number of records to return in result set.
Sort string Comma separated list of fields to sort by.

Response Parameters

Name Type Description
%MerchantApplicationSearchResult% object Returns results of merchant application search based on search parameters set.

Change History

Version Change
1.4 Added method

searchMerchantApplicationsCount

Reseller only method.

Identical to the searchMerchantApplications method except only the application counts are returned. Like searchMerchantApplications, this method returns MerchantApplicationSearchResult. The only difference is that MerchantApplicationSearchResult.Applications is left empty. This method provides a quicker way to determine the size of the result set before starting to retrieve the full search results.

Related Methods

Syntax

MerchantApplicationSearchResult searchMerchantApplicationsCount ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string Sort)

Request Parameters

Name Type Description
%ueSecurityToken% object Reseller security token, used to identify reseller and validate request.
%SearchParam% array Array of search parameters.
MatchAll boolean If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned.
Start integer Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200)
Limit integer Maximum number of records to return in result set.
Sort string Comma separated list of fields to sort by.

Response Parameters

Name Type Description
MerchantApplicationSearchResult object Returns results of merchant application search based on search parameters set.

searchMerchantApplicationsCustom

Reseller only method.

Use this method if you only need to view a few select fields of the applications you are searching for. Since it will only return the fields you specify, it is more efficient than the searchMerchantApplications method.

Related Methods

Syntax

string searchMerchantApplicationsCustom ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string FieldList, string Format, string Sort)

Request Parameters

Name Type Description
%ueSecurityToken% object Reseller security token, used to identify reseller and validate request.
%SearchParam% array Array of search parameters.
MatchAll boolean If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned.
Start integer Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200)
Limit integer Maximum number of records to return in result set.
Sort string Comma separated list of fields to sort by.
FieldList list List of fields to return in search.
Format string Specify format of return data. Possible formats include: csv, tab, xml.

Response Parameters

Name Type Description
searchMerchantApplicationsCustomReturn string Base64 encode result set. Returns all of the fields from any transactions matching your search parameters.

Change History

Version Change
1.4 Added method

getMerchantSummary

Example Request

    <?php

    try {

      $MerchantID=2;
      $StartDate='2007-01-01';
      $EndDate='2007-01-31';

      $res=$client->getMerchantSummary($restoken, $MerchantID, $StartDate, $EndDate);

      $this->assertEquals($res->MerchantID, $MerchantID);

      $this->assertTrue($res->SalesCount>1);

    }

    catch (SoapFault $e) {
      echo $client->__getLastRequest();
      echo $client->__getLastResponse();
      die("getMerchant failed: " .$e->getMessage());
    }

    ?>

    Dim MerchRefNum = 123456
    Dim StartDate = "2011-05-01"
    Dim EndDate = "2011-05-31"

    Dim Summary As resellerapi.MerchantSummary

    Try
        Summary = client.getMerchantSummary(token, MerchRefNum, StartDate, EndDate)
        MsgBox("Sales Count: " & Summary.SalesCount)

    Catch ex As Exception
        MsgBox("Exception: " & ex.Message)

    End Try

    BigInteger merchrefnum = new BigInteger("118227");
    MerchantSummary summary;
    summary = client.getMerchantSummary(restoken, merchrefnum, "2010-01-01", "2010-10-01");

    <?xml version="1.0" encoding="UTF-8"?>`
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:ns1="urn:ueresapi"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
      SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>`
    <ns1:getMerchantSummary>
      <Token xsi:type="ns1:ueSecurityToken">
        <ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
        <PinHash xsi:type="ns1:ueHash">
          <HashValue xsi:type="xsd:string">5cc04de62c82f2dad5ee51394b3a5bb012d231a3</HashValue>
          <Seed xsi:type="xsd:string">12819820871527226844</Seed>
          <Type xsi:type="xsd:string">sha1</Type>
        </PinHash>
        <SourceKey xsi:type="xsd:string">R:OYZG7PKcLqZ6XYaOOGy255w0K6YWc7</SourceKey>
      </Token>
      <MerchRefNum xsi:type="xsd:integer">117806</MerchRefNum>
      <Start xsi:type="xsd:string">2010-08-06</Start>
      <End xsi:type="xsd:string">2010-08-17</End>
    </ns1:getMerchantSummary>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Example Response

    <?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:ns1="urn:ueresapi"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
      SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
    <ns1:getMerchantSummaryResponse>
      <getMerchantSummaryReturn xsi:type="ns1:MerchantSummary">
        <CheckRefundsAmount xsi:type="xsd:double">235.9</CheckRefundsAmount>
        <CheckRefundsCount xsi:type="xsd:integer">80</CheckRefundsCount>
        <CheckSalesAmount xsi:type="xsd:double">91077.89</CheckSalesAmount>
        <CheckSalesCount xsi:type="xsd:integer">896</CheckSalesCount>
        <ReturnedCheckRefundAmount xsi:type="xsd:double">23</ReturnedCheckRefundAmount>
        <ReturnedCheckRefundCount xsi:type="xsd:integer">4</ReturnedCheckRefundCount>
        <ReturnedCheckSaleAmount xsi:type="xsd:double">46.01</ReturnedCheckSaleAmount>
        <ReturnedCheckSaleCount xsi:type="xsd:integer">3</ReturnedCheckSaleCount>
        <CheckChargebacksAmount xsi:type="xsd:double">117.78</CheckChargebacksAmount>
        <CheckChargebacksCount xsi:type="xsd:integer">17</CheckChargebacksCount>
        <SettledCheckRefundAmount xsi:type="xsd:double">7880.99</SettledCheckRefundAmount>
        <SettledCheckRefundCount xsi:type="xsd:integer">19</SettledCheckRefundCount>
        <SettledCheckSaleAmount xsi:type="xsd:double">5101.02</SettledCheckSaleAmount>
        <SettledCheckSaleCount xsi:type="xsd:integer">21</SettledCheckSaleCount>
        <CheckDepositCount xsi:type="xsd:integer">135</CheckDepositCount>
        <LargeCheckRefundsAmount xsi:type="xsd:double">3.12</LargeCheckRefundsAmount>
        <LargeCheckRefundsCount xsi:type="xsd:integer">4</LargeCheckRefundsCount>
        <LargeCheckSalesAmount xsi:type="xsd:double">14.88</LargeCheckSalesAmount>
        <LargeCheckSalesCount xsi:type="xsd:integer">3</LargeCheckSalesCount>
        <CreditsAmount xsi:type="xsd:double">0</CreditsAmount>
        <CreditsCount xsi:type="xsd:integer">0</CreditsCount>
        <DeclinesAmount xsi:type="xsd:double">0</DeclinesAmount>
        <DeclinesCount xsi:type="xsd:integer">0</DeclinesCount>
        <MerchRefNum xsi:type="xsd:integer">117806</MerchRefNum>
        <MerchantName xsi:type="xsd:string">Example Merchant</MerchantName>
        <SalesAmount xsi:type="xsd:double">0</SalesAmount>
        <SalesCount xsi:type="xsd:integer">0</SalesCount>
        <VoidsAmount xsi:type="xsd:double">0</VoidsAmount>
        <VoidsCount xsi:type="xsd:integer">0</VoidsCount>
      </getMerchantSummaryReturn>
    </ns1:getMerchantSummaryResponse>
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Reseller only method

This method allows you to view a summary of a specific merchant's activity during a specified time period. The start and end dates that you set for the search are inclusive.

Use the MerchantID (unique merchant identification assigned by the gateway) to fine the merchant whose activity you would like to view.

Activity included in the search results include details about the number of sales, credits, voids, declines, errors, checks and check refunds.

Related Methods

Syntax

MerchantSummary getMerchantSummary ( ueSecurityToken Token, integer MerchantID, string Start, string End )

Request Parameters

Name Type Description
%ueSecurityToken% object Reseller security token, used to identify reseller and validate request.
MerchantID integer Merchant ID number assigned by the gateway to an active merchant.
Start string Date for start of summary.
End string Date for end of summary.

Response Parameters

Name Type Description
%MerchantSummary% object Returns summary of merchant activity for specified time period.

Boarding Objects

BillingInfo

Contains billing information for a merchant or merchant application.

Contains the billing information for either an active merchant or a merchant application. It is submitted when adding a new merchant applications as part of the MerchantApplication object.

Places Used

Properties

Name Type Description
BankName String Name of merchant's bank (business checking, not merchant bank)
RoutingNumber String Routing number for merchant's checking account
AccountNumber String Account number for merchant's checking account
GatewayPackage String Name of the gateway package. Affects the merchant's monthly gateway fee and what features are enabled for them. Typical options are "Silver Package", "Gold Package (Cust DB)", "Gold Package (Fraud Center)" and "Platinum Package" unless reseller has configured custom packages.

ContactInfo

Contains contact information for a merchant application.

Contacts the contact information for a merchant application. This is a parameter in the MerchantApplication object.

Places Used

Properties

Name Type Description
Contact string First and last name of primary contact for merchant
Street string
Street2 string
City string
State string
Zip string
Country string
Email string Email address for primary contact
AltEmail string Alternate email for merchant
URL string Merchant's website (optional)
Fax string Fax number (optional)
Phone string Primary phone number for contact
MobilePhone string Mobile phone or alternate phone number for primary contact

Merchant

Contains contact information for an active merchant.

This object contains information for an active merchant.  This should not be confused with the MerchantApplication which contains the data on a new merchant application.

Places Used

Properties

Name Type Description
MerchRefNum integer gateway assigned Merchant ID
Activated string Date the merchant was created
ResellerEmail string Email address for reseller.
MerchantName string Company name of merchant, used to identify merchant
%ContactInfo% object Address and contact information for merchant
CallInPassword   string Optional call in password for merchant.   If a merchant has a call in password, they must provide this password to customer support staff before support will be given.  If no call in password is set,  support staff will verify merchant account info to clear the merchant
%BillingInfo%     object Billing information and gateway package
CreditCardPlatform string Name of the credit card processor to set the merchant up on.  Possible values are: FDMS, Tsys, Paymentech, Global, Planet Payment, MeS and Heartland.  Leave blank if no credit card processing is requested.
CreditCardPlatformSetup FieldValue Array of processor specific setup information
eCheckPlatform  string Name of the electronic check processor to set the merchant up on.
eCheckPlatformSetup FieldValue Array of processor specific setup information

MerchantApplication

Contains information for a merchant application.   

New merchants are added to the gateway by submitting a merchant application.   The application is reviewed for accuracy and if all information is correct, will be converted into an active merchant account.  Applications are typically activated within 1-2 hours during business hours and within 12 hours during non-business hours.

This object contains all of the information necessary for submitting a new merchant application. All fields must be passed. You only need to populate platform fields required by the platform specified. If a required field is left blank, a soapfault will be thrown, non-required fields must be passed, but may be left blank.

Places Used

Properties

Example Object

<?php
    $App=new stdClass();

    $App->ResellerEmail='applications@reseller.com';

    $App->ContactInfo = new stdClass();
    $App->MerchantName = "Acme Bagel Company";
    $App->ContactInfo->Contact = "John Doe";
    $App->ContactInfo->Street  ='4929 Wilshire Blvd';
    $App->ContactInfo->Street2 ='Suite 800';
    $App->ContactInfo->City    ='Los Angeles';
    $App->ContactInfo->State   ='CA';            
    $App->ContactInfo->Zip     ='90010';           
    $App->ContactInfo->Country ='US';        
    $App->ContactInfo->Email   = 'john@acme.com';
    $App->ContactInfo->Fax         ='012134567890';      
    $App->ContactInfo->Phone   ='687668678677';     
    $App->ContactInfo->MobilePhone='798787978788';
    $App->ContactInfo->AltEmail='mary@tmcode.com';
    $App->ContactInfo->URL = 'http://acme bagels.com';

    $App->BillingInfo = new stdClass();
    $App->BillingInfo->BankName = 'Bank of America';
    $App->BillingInfo->RoutingNumber = '12342313312';
    $App->BillingInfo->AccountNumber = '57655765754';
    $App->BillingInfo->GatewayPackage = 'Platinum Package';

    $App->CreditCardPlatform = 'FDMS';
    $App->CreditCardIndustry = 'Retail (Swipe)';
    $App->CreditCardPlatformSetup = array();
    $App->CreditCardPlatformSetup[] = array('Field'=>'MerchantNum', 'Value'=>'4454900399430020');
    $App->CreditCardPlatformSetup[] = array('Field'=>'MerchantID', 'Value'=>'382772891');
    $App->CreditCardPlatformSetup[] = array('Field'=>'TerminalID', 'Value'=>'112198000');

    $App->eCheckPlatform = 'Vericheck';
    $App->eCheckPlatformSetup = array();
    $App->eCheckPlatformSetup[] = array('Field'=>'DefaultSEC', 'Value'=>'TEL');
    $App->eCheckPlatformSetup[] = array('Field'=>'TaxID', 'Value'=>'123456789');
    $App->eCheckPlatformSetup[] = array('Field'=>'PIN', 'Value'=>'231');
    $App->eCheckPlatformSetup[] = array('Field'=>'MID', 'Value'=>'11231');
    $App->eCheckPlatformSetup[] = array('Field'=>'AcceptedSecCodes', 'Value'=>'TEL,PPD,CCD');

    $App->SourceKeyName = 'My Shopping Cart';
    $App->SourceKeyPin = '1351';
    $App->EmailSourceKeyTo = 'demo@acmebagels.com';

    $App->UserName = 'acmebagels';
    $App->EmailInstructionsTo = 'demo@acmebagels.com';

    $App->ApplicationNotes = 'An example note for merchant application';
    ?>

               MerchantApplication merchantapp = new MerchantApplication();


                merchantapp.setApplicationNotes("Application notes");

                BillingInfo billing = new BillingInfo();
                billing.setBankName("Example Bank");
                billing.setRoutingNumber("123456789");
                billing.setAccountNumber("910293112");
                billing.setGatewayPackage("Silver Package");
                merchantapp.setBillingInfo(billing);

                merchantapp.setCallInPassword("1234");
                ContactInfo contactinfo = new ContactInfo();
                contactinfo.setContact("John Doe");
                contactinfo.setStreet("4929 Wilshire Blvd");
                contactinfo.setStreet2("Suite 899");
                contactinfo.setCity("Los Angeles");
                contactinfo.setState("CA");
                contactinfo.setZip("90010");
                contactinfo.setCountry("US");
                contactinfo.setEmail("merchant@tmcode.com");
                contactinfo.setAltEmail("merchant@tmcode.com");
                contactinfo.setPhone("222-333-4446");
                contactinfo.setMobilePhone("222-333-4445");
                contactinfo.setFax("222-333-4444");
                contactinfo.setURL("http://www.acme.org");
                merchantapp.setContactInfo(contactinfo);

                merchantapp.setCreditCardIndustry("eCommerce");
                merchantapp.setCreditCardPlatform("FDMS");

                FieldValueArray platformdata = new FieldValueArray();
                platformdata.add(new FieldValue("MerchantNum","2334566356345"));
                platformdata.add(new FieldValue("MerchantID","1231230"));
                platformdata.add(new FieldValue("TerminalID","1231239"));
                merchantapp.setCreditCardPlatformSetup(platformdata);

                merchantapp.setECheckPlatform("Vericheck");
                FieldValueArray checkplatform = new FieldValueArray();
                checkplatform.add(new FieldValue("DefaultSEC","TEL"));
                checkplatform.add(new FieldValue("TaxID","123456789"));
                checkplatform.add(new FieldValue("PIN","231"));
                checkplatform.add(new FieldValue("MID","11231"));
                checkplatform.add(new FieldValue("AcceptedSecCodes","TEL,PPD,CCD"));
                merchantapp.setECheckPlatformSetup(checkplatform);

                merchantapp.setEmailInstructionsTo("merchant@tmcode.com");
                merchantapp.setEmailSourceKeyTo("merchant@tmcode.com");
                merchantapp.setMerchantName("Example Company");
                merchantapp.setResellerEmail("reselller@tmcode.com");
                merchantapp.setSourceKeyName("ShoppingCart");
                merchantapp.setSourceKeyPin("1234");
                merchantapp.setUserName("jdoe23");

Name Type Description
ResellerEmail           string       Email address for reseller.
MerchantName           string       Company name of merchant, used to identify merchant
%ContactInfo% object Address and contact information for merchant
CallInPassword         string       Optional call in password for merchant.   If a merchant has a call in password, they must provide this password to customer support staff before support will be given.  If no call in password is set,  support staff will verify merchant account info to clear the merchant
%BillingInfo%     BillingInfo                 Billing information and gateway package
SourceKeyName           string       Name of SourceKey to create when merchant is activated. Leave blank if no source key is requested
SourceKeyPin           string       Pin to assign to new SourceKey
EmailSourceKeyTo       string       Email address to send the new sourcekey to.  The email will contain the sourcekey but not the pin
UserName               string       Username of merchant user that will be created when the application is activated.  A password will be randomly assigned by the system.  Merchant must change the password the first time they log in
EmailInstructionsTo     string       Email address to send the merchant console instructions to. The email will include the merchants username and password
CreditCardPlatform     string       Name of the credit card processor to set the merchant up on.  Possible values are: FDMS, FDMS North, Tsys, Paymentech, Global, MeS, Rapid Connect, EPX and Heartland.  Leave blank if no credit card processing is requested.
CreditCardIndustry     string       Merchant Industry type: "eCommerce", "Mail Order", "Retail (Swipe)", "Hotel", "Restaurant", "Utility/Bill Pay", "Utility/Bill Pay (Card Present)"
CreditCardPlatformSetup   FieldValue Array of processor specific setup information (see below)
eCheckPlatform         string       Name of the electronic check processor to set the merchant up on. Possible values are: Vericheck, Checkgateway, Payliance, and Paya.  Leave blank if no check processing is requested.
eCheckPlatformSetup FieldValue Array of processor specific setup information (contact integration support for list of fields)
ApplicationNotes         string       Notes or instructions for gateway staff activating merchant account, ie "Hold application until 3/4/10"
MerchRefNum              integer      Contains the Merchant ID Number once the application has been activated
ApplicationID         integer      The gateway assigned Application ID
Status                   string        Contains the status of the application

Credit Card Platform Setup

The fields required vary depending on the platform being used. The following fields apply to all platforms:

Name Type Description
CreditPolicy string This sets the level of restrictions placed on a merchants ability to issue credits (refunds) to a credit cards. Possible values (listed from least to most restrictive): "No Restrictions", "Minimal Restrictions", "Require Prior Sale", "Connected Refunds Only", "Block All Credits"
AutoBatchClosure string The desired schedule for automatically closing the merchants open batch. If omitted, the setting from the selected Package will be used. Can either be every x hours: '6 hours', '12 hours', '24 hours', '36 hours', '48 hours', '72 hours' or it can be a specific time of day: '3:45pm'. Multiple closures can be specified in a comma separated list: '6:30am,7:39pm,11:55pm'
ConsoleVersion integer Set the desired console version

FDMS Nashville

Name Example Notes
MerchantNum 4120949485344948
MerchantID 0000000
TerminalID 0000000

FDMS North

Name Example Notes
MerchantID 123456789012
TerminalID alphanumeric 1234567
MCC 1234 Merchant category code (4 digits)
TaxID 000000000
Level3 Y Y/N - Denotes if level 3 processing should be enabled. Y to enable and N to disable. Defaults to disabled.
DefaultCommodityCode 00 Only required of Level 3 processing is enabled.

First Data Rapid Connect

Name Type Example Description
MerchantNum integer 4120949485344948
MerchantID string RCTST0000008056
TerminalID integer 1234567
MCC integer 1234 Merchant category code (4 digits)
GroupID integer 10001
TaxID integer 0000
SettlementID integer 987654321012 Settlement terminal id
Level3 boolean Y Denotes if level 3 processing should be enabled. Y to enable and N to disable. Defaults to disabled.
DefaultCommodityCode integer 00 Only required of Level 3 processing is enabled.
PinDebitSupport boolean Set to 'True' to enable debit processing

Tsys

Name Example Notes
AcquirerBIN 123456
MerchantNum 891234567890
AgentBank 000000
AgentChain 000000
StoreNumber 0001
TerminalNumber 0001
MCC 1234 Merchant category code (4 digits)
VNumber 1234567 Only needed for Tsys
MerchantName ACME BAGELS Merchant name as it will appear on cardholder statement
MerchantState CA
MerchantZip 90010
ServicePhoneNumber 3239312233 Customer Service number for merchant
AmexLevel2 Y Merchant is enrolled to process level 2 corporate purchasing cards (Y/N)
PinDebitSupport boolean Set to 'True' to enable debit processing
DebitNetworks V,P,T Comma separated list of one character debit network codes
Level3 boolean Y

MeS and Heartland

Name Example Notes
AcquirerBIN 123456
MerchantNum 891234567890
AgentBank 000000
AgentChain 000000
StoreNumber 0001
TerminalNumber 0001
MCC 1234 Merchant category code (4 digits)
VNumber 1234567 Only needed for Tsys
MerchantName ACME BAGELS Merchant name as it will appear on cardholder statement
MerchantState CA
MerchantZip 90010
ServicePhoneNumber 3239312233 Customer Service number for merchant
AmexLevel2 Y Merchant is enrolled to process level 2 corporate purchasing cards (Y/N)
PinDebitSupport boolean Set to 'True' to enable debit processing

Paymentech

Name Example Notes
ClientNumber 1234
MerchantID 012345678901
TerminalNumber 001

Global

Name Example Notes
BankID 123456
MerchantID 4567890123456

EPX

Name Type Example Description
CustNum string 5001 Max length of 16 numeric digits - This will usually be 4 digits
MerchNum string 3130030000000 Max length of 16 numeric digits
TerminalNum string 1 Max length of 16 numeric digits
DbaNum string 1 Max length of 16 numeric digits
Mac string 1 Max length of 80 numeric digits (optional)
PinDebitSupport boolean Set to 'True' to enable debit processing

Vantiv

Name Type Description
BankID integer 123456
MerchantID integer 567890123456
TerminalID integer 001
DebitTerminalID integer 000
PinDebitSupport boolean Set to 'True' to enable debit processing

Check Platform Setup

The fields required vary depending on the platform being used. The following fields apply to all platforms:

Vericheck

Name Type Description
DefaultSEC string Default Check Format. Click here for more info on check formats.
TaxID string
PIN string
MID string

Checkgateway

Name Type Description
DefaultSEC string Default Check Format. Click here for more info on check formats.
Username string Required

Paya

Name Type Description
DefaultSEC string Default Check Format. Click here for more info on check formats.
TerminalID_WEB string
TerminalID_POP string
TerminalID_TEL string
TerminalID_PPD string
TerminalID_CCD string
TerminalID_C21 string

Payliance

Name Type Description
DefaultSEC string Default Check Format. Click here for more info on check formats.
MerchantID string Required
Password string Required
Location string Required

CrossCheck

Parameter Type Description
Username string Required
Password string Required

ACH Solutions

Parameter Type Description
Username string Required
Password string Required
DefaultSEC string Default Check Format. Click here for more info on check formats.

Reliafund

Parameter Type Description
Username string Required
Password string Required
DefaultSEC string Default Check Format. Click here for more info on check formats.

Actum

Parameter Type Description
TELParentID string
TELSubID string
TELUsername string
TELPassword string
TELSystemPassword string
PPDParentID string
PPDSubID string
PPDUsername string
PPDPassword string
PPDSystemPassword string
CCDParentID string
CCDSubID string
CCDUsername string
CCDPassword string
CCDSystemPassword string
WEBParentID string
WEBSubID string
WEBUsername string
WEBPassword string
WEBSystemPassword string
DefaultSEC string Default Check Format. Click here for more info on check formats.

MerchantApplicationSearchResult

Contains the results of a merchant search.

This object is returned by the searchMerchantApplications method. It describes the result of the search, including the total number of merchants matched, the number being returned, and an array of MerchantObjects.

Places Used

Properties

Name Type Description
Limit integer The maximum number of merchants to be returned.
%Applications% object An array of Merchant application objects that match the search criteria.
ApplicationsMatched integer Number of merchants applications matched by search criteria.
ApplicationsReturned integer Number of merchants applications contained in this search result.
StartIndex integer The index where this result set begins (default is 0).

MerchantSearchResult

Contains the results of a merchant search.

This object is returned by the searchMerchants method. It describes the result of the search, including the total number of merchants matched, the number being returned, and an array of MerchantObjects.

Places Used

Properties

Name Type Description
MerchantsMatched integer Number of merchants matched by search criteria.
MerchantsReturned integer Number of merchants contained in this search result.
StartIndex integer The index where this result set begins (default is 0).
Limit integer The maximum number of merchants to be returned.
%Merchant% object An array of MerchantObjects matched by search criteria.

MerchantSummary

Summary of merchant activity over a given time period.

Time period to be analyzed must be specified in the initial search using the getMerchantSummary method. All information returned applies only to the specified time period and is not a definitive total of all of the merchant's transaction information. The summary data is not real time and can lag up to 2 hours.

Places Used

Properties

Name Type Description
MerchantID integer Merchant ID (assigned by the gateway).
MerchantName string Name of the merchant whose activity you are searching.
SalesCount integer Total number of sales processed by the merchant.
SalesAmount double Total dollar amount of sales processed.
CreditsCount integer Total number of credits processed by the merchant.
CreditsAmount double Total dollar amount of credits processed.
VoidsCount integer Total number of voids processed by the merchant.
VoidsAmount double Total dollar amount of voids processed.
DeclinesCount integer Total number of declines processed by the merchant.
DeclinesAmount double Total dollar amount of declines processed
CheckSalesCount integer Total number of check sales processed (by date entered)
CheckSalesAmount double Total dollar amount of check sales processed (by date entered)
CheckRefundsCount integer Total number of check refunds processed (by date entered)
CheckRefundsAmount double Total dollar amount of check refunds processed (by date entered)
ReturnedCheckSaleCount integer Total number of check sales returned (by date returned)
ReturnedCheckSaleAmount double Total dollar amount of check sales returned (by date returned)
ReturnedCheckRefundCount integer Total number of check refunds returned (by date returned)
ReturnedCheckRefundAmount double Total dollar amount of check refunds returned (by date returned)
CheckChargebacksCount integer Total number of check sales returned as chargebacks (by date returned)
CheckChargebacksAmount double Total dollar amount of check sales returned as chargebacks (by date returned)
SettledCheckSaleCount integer Total number of check sales settled (by date settled)
SettledCheckSaleAmount double Total dollar amount of check sales settled (by date settled)
SettledCheckRefundCount integer Total number of check refunds settled (by date settled)
SettledCheckRefundAmount double Total dollar amount of check refunds settled (by date settled)
LargeCheckSalesCount integer Total number of large check sales processed (by date entered). Large checks are any ach transaction that exceeds a merchants defined threshold (typically $5,000)
LargeCheckSalesAmount double Total dollar amount of large check sales processed (by date entered)
LargeCheckRefundsCount integer Total number of large check refunds processed (by date entered)
LargeCheckRefundsAmount double Total dollar amount of Large check refunds processed (by date entered)
CheckDepositCount integer Total number of ach batches deposited to merchant (not support for all ach platforms)

%ueHash%

Name Type Description
Type string Hashing Function Used: Currently only "md5" and "sha1" are supported.
Seed string The data used to seed the hash: This value must be unique and cannot be reused. The system will reject the request if a Seed is reused. The reason for this is to minimize the damage if a HashValue is stolen. An intruder may manage to obtain a SourceKey and a HashValue, but will not be able to use the source key since the HashValue is based on a seed that cannot be reused.
HashValue string Hash string: The resulting hash. The hash is calculated by concatenating the SourceKey, the Seed and the Pin value. Do not place any characters in between these values. Once the values have been concatenated, calculate the hash string using the algorithm specified by Type.

%ueSecurityToken%

Name Type Description
SourceKey string SourceKey obtained in merchant console.
PinHash ueHash Hash object for the PIN (only necessary if this source key has a pin assigned)
ClientIP string The IP Address of the end client

%AccountDetails%

Name Type Description
CreditCardPlatform string Name of Card Processing Platform, "Disabled" if no credit card support
Industry string Account Industry (eCommerce, Mail Order, Retail, Restaurant, Hotel)
CheckPlatform string Name of Check Processor, "Disabled" if no support for checks.
CardholderAuthentication string Integrated cardholder authentication (Verified by Visa or MC 3D Secure)
DebitCardSupport boolean True if merchant has support for processing pin based debit cards
DirectPayPlatform string Name of the direct payment platform if supported
CurrencyObject object Array of currencies supported by merchant. Empty if using a non-multicurrency enabled credit card processor.

%Applications%

Name Type Description
ResellerEmail string Email address for reseller.
MerchantName string Company name of merchant, used to identify merchant
ContactInfo object Address and contact information for merchant
CallInPassword string Optional call in password for merchant.   If a merchant has a call in password, they must provide this password to customer support staff before support will be given.  If no call in password is set,  support staff will verify merchant account info to clear the merchant
BillingInfo object Billing information and gateway package
CreditCardPlatform string Name of the credit card processor to set the merchant up on.  Possible values are: FDMS, Tsys, Paymentech, Global, Planet Payment, MeS and Heartland.  Leave blank if no credit card processing is requested.
CreditCardIndustry string Merchant Industry type: "eCommerce", "Mail Order", "Retail (Swipe)", "Hotel", "Restaurant", "Utility/Bill Pay", "Utility/Bill Pay (Card Present)"
MerchRefNum integer Contains the Merchant ID Number once the application has been activated
AppRefNum integer Contains the Merchant Application ID Number once the application has been submitted.
Status string Contains the status of the application

%BatchStatus%

Name Type Description
BatchKey string Batch reference number (assigned by the gateway).
BatchRefNum string A unique batch reference number assigned by the gateway.
Sequence integer Batch sequence number
Status string Status of this batch (ie: open, closing, closed)
Opened string Date/time the batch was opened (first transaction was run)
Closed string Date/time the batch was closed (if it has been closed)
Scheduled string Date/time the batch is scheduled to close
TransactionCount integer Number of transactions in the batch
SalesCount integer Number of sales in the batch
CreditsCount integer Number of credits in the batch
VoidsCount integer Number of voids in the batch
SalesAmount double Dollar amount of the sales
CreditsAmount double Dollar amount of the credits
NetAmount double Dollar amount of the sales-credits
VoidsAmount double Dollar amount of the voids

%BatchSearchResult%

Name Type Description
BatchKey string Batch reference number (assigned by the gateway).
BatchRefNum string A unique batch reference number assigned by the gateway.
Sequence integer Batch sequence number
Status string Status of this batch (ie: open, closing, closed)
Opened string Date/time the batch was opened (first transaction was run)
Closed string Date/time the batch was closed (if it has been closed)
Scheduled string Date/time the batch is scheduled to close
TransactionCount integer Number of transactions in the batch
SalesCount integer Number of sales in the batch
CreditsCount integer Number of credits in the batch
VoidsCount integer Number of voids in the batch
SalesAmount double Dollar amount of the sales
CreditsAmount double Dollar amount of the credits
NetAmount double Dollar amount of the sales-credits
VoidsAmount double Dollar amount of the voids

%BatchUploadStatus%

Name Type Description
UploadRefNum string Upload reference number (assigned by the gateway).
Status String Current status of the upload batch.
Started String Date and time the batch upload was initiated.
Finished String Date and time the batch upload was completed.
Transactions Integer Total number of transactions in the upload batch.
Remaining Integer Number transactions remaining to be run.
Approved Integer Number of transactions that have been approved.
Declined Integer Number of transactions that have been declined.
Errors Integer Number of transactions that resulted in errors.

%BillingAddress%

Name Type Description
FirstName String Customer's First Name
LastName String Customer's Last Name
Company String Company or Organization Name
Street String Street Address Line 1
Street2 String Street Address Line 2
City String City
State String State or Province
Zip String Zip or Postal Code
Country String Country
Phone String Telephone Number
Fax String Fax Number
Email String Email Address

%BillingInfo%

Name Type Description
BankName String Name of merchant's bank (business checking, not merchant bank)
RoutingNumber String Routing number for merchant's checking account
AccountNumber String Account number for merchant's checking account
GatewayPackage String Name of the gateway package. Affects the merchant's monthly gateway fee and what features are enabled for them. Typical options are "Silver Package", "Gold Package (Cust DB)", "Gold Package (Fraud Center)" and "Platinum Package" unless reseller has configured custom packages.

%CheckData%

Name Type Description
CheckNumber Integer Check number of check being used for transaction.
Routing String Nine digit bank routing number.
Account String Bank account number.
AccountType String Checking or Savings - if left blank, default is Checking.
DriversLicense String Driver's license of checking account holder.
DriversLicenseState String Driver's license state of issue.
RecordType String Record type of electronic check transaction. Not supported by all check processors. List of Check Record Types
MICR String MICR Data for Check 21 (optional, depending on processor)
AuxOnUS String MICR Data for Check 21 (optional, depending on processor)
EpcCode String MICR Data for Check 21 (optional, depending on processor)
FrontImage String Scan of front of check, base64 encoded (optional)
BackImage String Scan of back of check, base64 (optional)
SSN String Customer Social Security Number

%CheckTrace%

Name Type Description
Status string Text description of the status code.
StatusCode string A single letter code indicating the status of a transaction.
TrackingNum string Reference number assigned by check processor.
Effective string Date check was originally posted.
Processed string Date check was received by processor.
Settled string Date check was originally settled.
Returned string Date check was returned.
ReturnCode string
Reason string
BankNote string Note from checking account holder's bank. Typically this note will explain the reason for a returned check, but it may also indicate future changes to routing/account number even if the electronic check transaction was approved. For example, if the customer's bank has been bought by another bank, the original routing number will only remain valid for about a year. During this period, the bank will send back a note indicating the new routing number.

%ContactInfo%

Name Type Description
Contact string First and last name of primary contact for merchant
Street string
Street2 string
City string
State string
Zip string
Country string
Email string Email address for primary contact
AltEmail string Alternate email for merchant
URL string Merchant's website (optional)
Fax string Fax number (optional)
Phone string Primary phone number for contact
MobilePhone string Mobile phone or alternate phone number for primary contact

%CreditCardData%

Name Type Description
CardType string Card Type - describes card issuer (Visa, MC, Amex, Discover). Read only property (ignored if sent as a parameter to transaction methods).
CardNumber string Card Number
CardExpiration string Expiration Date - Should be set to 4 digit MMYY.
CardCode string CVV2/CID card code value from back of card. Set to -2 if the code is not legible, -9 if the code is not on the card.
AvsStreet string Billing address associated with card, used by AVS.
AvsZip string Billing zipcode associated with card, used by AVS.
CardPresent boolean Indicates if the card is present during the transaction (ie: the card was swiped at a POS terminal). Used to indicate retail.
MagStripe string Track 1 and/or Track 2 data for swiped transactions. For unencrypted swipers send the raw data. For encrypted swipers please look at end to end encryption
DataSource string Entry mode of transaction. (Contactless, Card Not Present- Manually Keyed, Card Swiped, Chip Read)
DUKPT string DUKPT encrypted pin block. Only required for pin debit transactions. The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the Pin Pad serial number and transaction counter.
Signature string Signature capture image. Base64 encoded.
TermType string Terminal type (POS, StandAlone, Unattended, or Unknown). May be left blank if unknown.
MagSupport string Indicates whether software has support for mag swipe (Yes, No, Unknown).
XID string XID value received from 3rd party Visa VPAS or MC UCAF.
CAVV string CAVV value received from 3rd party Visa VPAS or MC UCAF.
ECI integer ECI value.
InternalCardAuth boolean Use gateway based authentication for Visa VPAS or MC UCAF.
Pares string Pares returned by client after successful

%CreditCardToken%

Name Type Description
CardRef string Unique token representing card
CardExpiration string Expiration Date of credit card
CardNumber string Masked card number
CardType string Type of card

%CurrencyConversion%

Name Type Description
FromCurrency string Code of currency that transaction amount is being converted from.
FromAmount double Amount being converted. This amount is shown in the original currency, before the conversion takes place (FromCurrency).
Currency string Code of currency that transaction amount is being converted to.
Rate double Conversion rate used.
Amount double Amount converted to new currency. This amount is shown in the new currency that the amount has been converted to (Currency).

%CurrencyObject%

Name Type Description
NumericCode integer 3 digit numeric currency code to be used when processing transactions in the corresponding currency.
TextCode string 3 character currency code (ie: USD or EUR).
Currency string Full name of currency (ie: US Dollars or Euros).
Rate double Currency's current conversion rate. This is the conversion rate to the merchant's specified settling currency.
DecimalPlaces integer Number of positions to the right of the decimal (or whole units separator). Used for rounding (ie for USD 12.88, DecimalPlaces=2, for Japanese Yen 512 DecimalPlaces=0).

%CustomerObject%

Name Type Description
CustNum string Customer Number (System assigned)
CustKey string Customer Number (System assigned)
CustomerID string Customer ID (Merchant assigned)
BillingAddress object Billing Address
PaymentMethod array Array of PaymentMethod objects. Multiple credit cards or ACH accounts may be stored for each customer.
CustomData string Custom data is a raw text field, please serialize and encode (ie: base64) your data so that complex types are stored and retrieved correctly.
CustomFields array Array of field values containing the merchant defined customer fields. These fields are defined in the merchant console.
URL string URL for customers website
Created string Date/Time customer was created (Read Only)
Modified string Date/Time customer was last changed (Read Only)
Enabled boolean Notes whether or not a customer has been enabled for a recurring billing cycle. The customer billing does not need to be enabled to run one time transactions via the runCustomerTransaction method.
Schedule string Recurring billing schedule, if any. Possible values include: daily, weekly, bi-weekly (every two weeks), monthly, bi-monthly (every two months), quarterly, bi-annually (every six months), annually, first of month, last day of month.
NumLeft string Number of transactions remaining in customer's recurring billing cycle. "-1" indicates unlimited transactions.
Next string Date of customer's next scheduled transaction.
Amount double Total Amount to be billed in recurring billing cycle.
Tax double Portion of Amount that is Tax
Currency string Numeric currency code for Amount. (Only needed if multicurrency merchant account)
Description string Description of transaction.
OrderID string Transaction Order ID
User string Merchant username assigned to billing.
Source string Name of source key assigned to billing.
SendReceipt boolean Send client a receipt.
ReceiptNote string Note to send on receipt.
Failures integer Number of failures since last approval.
PriceTier string Name of customer price tier
TaxClass string Tax Class (Group)
LookupCode string Lookup code from customer/member id card. Either barcode or Magnetic stripe. Can be assigned by merchants. Defaults to system assigned if left blank.

%CustomerSearchResult%

Name Type Description
CustomersMatched integer Total number of customers matched by search criteria.
CustomersReturned integer Total number of customers contained in search result.
StartIndex integer The index where this result set begins (default is 0).
Limit integer The maximum number of customers to be returned in the search.
CustomerObject array An array of CustomerObjects matched by search criteria.

%CustomerTransactionRequest%

Name Type Description
Command string Processing command to run. Possible values: Sale, AuthOnly, Credit, Check and CheckCredit. If a blank is passed, the default value is Sale for credit card or Check for checks
IgnoreDuplicate boolean Do not check for duplicate transaction. Set to "true" if you would like to override the duplicate transaction handling.
Details object Transaction details: amount, clerk, currency,
ClientIP string IP Address of client.
CustReceipt boolean Customer Receipt. Set to "true" if you would like the gateway to send an email to customer.
CustReceiptEmail string Email address to receipt to. If left blank, the receipt will be sent to the email address stored in the customer record.
CustReceiptName string Customer Receipt Template Name. Specify the name of the template to use. (Optional)
MerchReceipt boolean Send Merchant Receipt. Set to "true" if you would like the gateway to send a receipt to the merchant.
MerchReceiptEmail string Email address to receipt to. Required if MerchReceipt is set to true
MerchReceiptName string Merchant Receipt Template Name. Specify the name of the template to use. (Optional)
CustomFields array Array of FieldValue pairs. Additional transaction api fields (ie UMtimeout) can also be passed in via this array. Any field name starting with UM is assumed to be an api field and not a custom field.
isRecurring boolean Recurring flag Signals to the platform that this transaction is a recurring billing transaction. Use with caution, can cause downgrades if not used properly. Defaults to false which causes the transaction to run as a normal card not present transaction.
InventoryLocation string ID of warehouse to draw inventory from. If blank, uses setting from source key. If no setting in source key, inventory will not be adjusted.
CardCode string CVV2/CVC card id code. PCI requirements forbid storing CVV2 value. Customer must be prompted to enter this value each time a transaction is run. This value is not required unless CVV2 validation is desired.
LineItem array Array of line item details
Software string Free form string that can be used by the developer to record information about their software, version, build number or operating system details. Reported on the transaction detail screen, in custom reports or via api. (optional)
XID string XID value received from 3rd party Visa VPAS or MC UCAF. Can be sent with transaction, but cannot be stored in method.
CAVV string CAVV value received from 3rd party Visa VPAS or MC UCAF. Can be sent with transaction, but cannot be stored in method.
ECI integer ECI value. Can be sent with transaction, but cannot be stored in method.

%CustomFields%

Name Type Description
Field string Name of element.
Value string Value of element.

%Details%

Name Type Description
Invoice string Transaction invoice number. Will be truncated to 10 characters. If this field is not provided, the system will submit the RefNum in its place.
PONum string Purchase Order Number for commercial card transactions - 25 characters. (Required for Level 2 & 3)
OrderID string Transaction order ID. This field should be used to assign a unique order id to the transaction. The order ID can support 64 characters.
SessionID string Optional Session ID used for customer analytics and fraud prevention. Must be get generated using the getSession method. See the profiling guide for more information
Clerk string Sales Clerk. Optional value indicating the clerk/person processing transaction, for reporting purposes.
Terminal string Terminal Name. Optional value indicating the terminal used to process transaction, for reporting purposes.
Table string Restaurant Table Number. Optional value indicating the restaurant table, for reporting purposes
LaneID string POS identification number set by merchant.
Description string Transaction description.
Comments string Comments. Free form text.
AllowPartialAuth boolean Allow a partial authorization if full amount is not available (Defaults to false)
Amount double Total billing amount. (Subtotal+Tax+Tip+Shipping-Discount=Amount.)
Currency string Currency Code. 3 digit currency code of total amount.
Tax double Portion of total amount that is tax. (Required for Level 2 & 3)
Tip double Portion of total amount that is tip.
NonTax boolean Determines whether a transaction is non-taxable.
Shipping double Portion of total amount that is shipping charges. (Required for Level 3)
ShipFromZip double Zipcode that the order is shipping from. (Required for Level 3)
Discount double Amount of discount.
Duty double Amount of duty charged. (Required for Level 3)
Subtotal double The amount of the transaction before tax, tip, shipping and discount have been applied.
CashBack string Denotes the amount of cashback customer requested.
DigitalGoods string Denotes the products were virtual or physical

%FieldValue%

Name Type Description
Field string Name of element.
Value string Value of element.

%LineItem%

Name Type Description
ProductRefNum string Unique ID of the product assigned by the gateway (Optional)
ProductKey string Unique ID of the product assigned by the gateway
SKU string A stock-keeping unit is a unique identifier for each distinct product and service that can be purchased
ProductName string Name of the product
Description string Description of product or purchase
UnitPrice string Individual price of the unit
Qty string Total number of items
Taxable boolean Taxable good flag
CommodityCode string Numeric code used to classify the good or service. See the UNSPSC for codes. (Level 3)
UnitOfMeasure string Unit that quantity is measuring. Defaults to "EA". See list of valid Unit of Measure Codes (Level 3)
DiscountAmount string Amount line item was discounted (Level 3)
DiscountRate string The rate used to calculate discount (Level 3)
TaxAmount string Tax charged for this line item (Level 3)
TaxRate string The tax rate used for this line item (Level 3)

%LodgingDetails%

Name Type Description
Folio string Guest account reference number
RoomRate string Rate of room
Nights string How many nights the reservation is for
CheckInDate string Date guest will check in.
CheckOutDate string Date guest will check out.
ExtraChargeReasons string Comment field denoting why guest was charged extra.
RoomNumber string Guests room number
CustomerCode string Reference number for the guest
LengthOfStay string How long the guest will be staying
RoomTaxRate string Tax percentage for the room type booked.
NonRoomCharges string Any charges made outside of the booking costs. (Room Service, etc.)
RoomTaxAmount string Tax amount in dollars for the room.
PreferredCustomer string Denotes if this guest is a preferred customer.
ChargeType string Denotes how guest paid for the room.
DepartureTime string Time and date guest departed.
ArrivalTime string Time and date the guest arrived

%Merchant%

Name Type Description
MerchRefNum integer gateway assigned Merchant ID
Activated string Date the merchant was created
ResellerEmail string Email address for reseller.
MerchantName string Company name of merchant, used to identify merchant
ContactInfo object Address and contact information for merchant
CallInPassword   string Optional call in password for merchant.   If a merchant has a call in password, they must provide this password to customer support staff before support will be given.  If no call in password is set,  support staff will verify merchant account info to clear the merchant
BillingInfo     object Billing information and gateway package
CreditCardPlatform string Name of the credit card processor to set the merchant up on.  Possible values are: FDMS, Tsys, Paymentech, Global, Planet Payment, MeS and Heartland.  Leave blank if no credit card processing is requested.
CreditCardPlatformSetup FieldValue Array of processor specific setup information
eCheckPlatform  string Name of the electronic check processor to set the merchant up on.
eCheckPlatformSetup FieldValue Array of processor specific setup information

%MerchantApplication%

Name Type Description
ResellerEmail           string       Email address for reseller.
MerchantName           string       Company name of merchant, used to identify merchant
ContactInfo object Address and contact information for merchant
CallInPassword         string       Optional call in password for merchant.   If a merchant has a call in password, they must provide this password to customer support staff before support will be given.  If no call in password is set,  support staff will verify merchant account info to clear the merchant
BillingInfo     BillingInfo                 Billing information and gateway package
SourceKeyName           string       Name of SourceKey to create when merchant is activated. Leave blank if no source key is requested
SourceKeyPin           string       Pin to assign to new SourceKey
EmailSourceKeyTo       string       Email address to send the new sourcekey to.  The email will contain the sourcekey but not the pin
UserName               string       Username of merchant user that will be created when the application is activated.  A password will be randomly assigned by the system.  Merchant must change the password the first time they log in
EmailInstructionsTo     string       Email address to send the merchant console instructions to. The email will include the merchants username and password
CreditCardPlatform     string       Name of the credit card processor to set the merchant up on.  Possible values are: FDMS, FDMS North, Tsys, Paymentech, Global, MeS, Rapid Connect, EPX and Heartland.  Leave blank if no credit card processing is requested.
CreditCardIndustry     string       Merchant Industry type: "eCommerce", "Mail Order", "Retail (Swipe)", "Hotel", "Restaurant", "Utility/Bill Pay", "Utility/Bill Pay (Card Present)"
CreditCardPlatformSetup   FieldValue Array of processor specific setup information (see below)
eCheckPlatform         string       Name of the electronic check processor to set the merchant up on. Possible values are: Vericheck, Checkgateway, Payliance, and Paya.  Leave blank if no check processing is requested.
eCheckPlatformSetup FieldValue Array of processor specific setup information (contact integration support for list of fields)
ApplicationNotes         string       Notes or instructions for gateway staff activating merchant account, ie "Hold application until 3/4/10"
MerchRefNum              integer      Contains the Merchant ID Number once the application has been activated
ApplicationID         integer      The gateway assigned Application ID
Status                   string        Contains the status of the application

%MerchantApplicationSearchResult%

Name Type Description
Limit integer The maximum number of merchants to be returned.
Applications object An array of Merchant application objects that match the search criteria.
ApplicationsMatched integer Number of merchants applications matched by search criteria.
ApplicationsReturned integer Number of merchants applications contained in this search result.
StartIndex integer The index where this result set begins (default is 0).

%MerchantSearchResult%

Name Type Description
MerchantsMatched integer Number of merchants matched by search criteria.
MerchantsReturned integer Number of merchants contained in this search result.
StartIndex integer The index where this result set begins (default is 0).
Limit integer The maximum number of merchants to be returned.
Merchant object An array of MerchantObjects matched by search criteria.

%MerchantSummary%

Name Type Description
MerchantID integer Merchant ID (assigned by the gateway).
MerchantName string Name of the merchant whose activity you are searching.
SalesCount integer Total number of sales processed by the merchant.
SalesAmount double Total dollar amount of sales processed.
CreditsCount integer Total number of credits processed by the merchant.
CreditsAmount double Total dollar amount of credits processed.
VoidsCount integer Total number of voids processed by the merchant.
VoidsAmount double Total dollar amount of voids processed.
DeclinesCount integer Total number of declines processed by the merchant.
DeclinesAmount double Total dollar amount of declines processed
CheckSalesCount integer Total number of check sales processed (by date entered)
CheckSalesAmount double Total dollar amount of check sales processed (by date entered)
CheckRefundsCount integer Total number of check refunds processed (by date entered)
CheckRefundsAmount double Total dollar amount of check refunds processed (by date entered)
ReturnedCheckSaleCount integer Total number of check sales returned (by date returned)
ReturnedCheckSaleAmount double Total dollar amount of check sales returned (by date returned)
ReturnedCheckRefundCount integer Total number of check refunds returned (by date returned)
ReturnedCheckRefundAmount double Total dollar amount of check refunds returned (by date returned)
CheckChargebacksCount integer Total number of check sales returned as chargebacks (by date returned)
CheckChargebacksAmount double Total dollar amount of check sales returned as chargebacks (by date returned)
SettledCheckSaleCount integer Total number of check sales settled (by date settled)
SettledCheckSaleAmount double Total dollar amount of check sales settled (by date settled)
SettledCheckRefundCount integer Total number of check refunds settled (by date settled)
SettledCheckRefundAmount double Total dollar amount of check refunds settled (by date settled)
LargeCheckSalesCount integer Total number of large check sales processed (by date entered). Large checks are any ach transaction that exceeds a merchants defined threshold (typically $5,000)
LargeCheckSalesAmount double Total dollar amount of large check sales processed (by date entered)
LargeCheckRefundsCount integer Total number of large check refunds processed (by date entered)
LargeCheckRefundsAmount double Total dollar amount of Large check refunds processed (by date entered)
CheckDepositCount integer Total number of ach batches deposited to merchant (not support for all ach platforms)

%PaymentMethod%

Name Type Description
MethodType string Type of payment method (CreditCard, ACH, StoredValue or Invoice)
MethodID string ID of payment method. This property is ignored when adding a new payment method but required if updating an existing method.
MethodName string Label for payment method. For example "Work Visa" or "Personal Checking."
SecondarySort integer If set to value greater than 0, use this method as backup in case default fails. Secondary methods will be run in ascending order.
Created string Date and time the method was created.
Modified string Date and time the method was last modified.
Expires string Date on which payment method will expire. Do not leave blank. Format: YYYY-MM-DD
CardHolder string Name of the card holder on credit/debit card.
CardNumber string Credit card number (required for credit cards). If data is coming from a swiper, base64_encode the entire raw block read from the swiper device and put %%enc://%% at the beginning. Example: %%enc://%%AAbbCdEEaa...
CardExpiration string Credit card expiration date in YYYY-MM format. It will also accept MMYY format. (required for credit cards)
AvsStreet string Street address for AVS (address verification system). (Optional but recommended for credit cards)
AvsZip string Zip code for AVS. (Optional but recommended for credit cards)
CardCode string CVV2/CID card identification code. This code is not stored and is only used when verifying a new payment method before it is added. (Optional for credit cards)
CardType string Type of credit card (Visa, Mastercard, etc). This is a read only parameter and will be ignored if set.
XID string XID value received from 3rd party Visa VPAS or MC UCAF. Can be sent with transaction, but cannot be stored in method.
CAVV string CAVV value received from 3rd party Visa VPAS or MC UCAF. Can be sent with transaction, but cannot be stored in method.
ECI integer ECI value. Can be sent with transaction, but cannot be stored in method.
Account string ACH Bank Account Number (required for checks)
AccountType string ACH Type of Bank Account (Checking or Savings, defaults to checking)
Routing string ACH Bank Routing Number (required for checks)
DriversLicense string Drivers license number used for check guarantee (optional)
DriversLicenseState string Drivers license state (optional)
RecordType string ACH transaction type (optional, should be left blank unless instructed differently by check processor)
MaxBalance double The maximum balance that may be charged on Invoice before transactions are declined
Balance double The funds left on the account. Transactions against this payment method may not exceed this balance
AutoReload boolean Set true if StoredValue card should automatically be reloaded
ReloadSchedule string Automatic reload schedule
ReloadThreshold double Balance that will trigger an automatic reload
ReloadAmount double Amount to automatically reload
ReloadMethodID string Payment method to use for reloading card

%PriceTier%

Name Type Description
Qty string Qty threshold for price
Price string Product Price
CustomerTier string Customer based price tier identifier

%Product%

Name Type Description
ProductRefNum string Gateway assigned ID of product
ProductKey string Unique ID of the product assigned by the gateway
ProductID string Merchant assigned product ID
Category string Product category
SKU string Stock-Keeping Unit
UPC string Universal Product Code
Enabled boolean Enables the ability to store products
Name string Name of the product
Description string Product description
Model string Model of the product
Weight string Weight of the product
ShipWeight string Shipping weight of the product
Price double Price of the product
WholesalePrice double Wholesale price of the product
ListPrice double List price of the product
PriceTier object Qty and Customer based variable pricing tiers
TaxClass string Product's Tax Class
DateAvailable string Date the product is available for sale
Manufacturer string Maker of the product
PhysicalGood boolean Tangible/Shippable good.
MinQuantity integer Minimum quantity allowed
ImageURL string URL address of the product image
URL string URL of the product
ProductInventory object Product inventory levels
Modified string Date/time the product was last changed
Created string Date/time the product was created

%ProductCategory%

Name Type Description
ProductCategoryRefNum string Gateway assign unique reference number
ProductCategoryKey string Gateway assign unique reference number
Name string Name of product category
Created string Timestamp for when the category was created
Modified string Timestamp for when the category was last modified

%ProductInventory%

Name Type Description
InventoryLocationKey string Gateway assign unique reference number
InventoryLocation string Location of Inventory (Warehouse or location name)
QtyOnHand string Count of available units in stock
QtyOnOrder string Count of units on order (scheduled to be available on DateAvailable)
DateAvailable string Date that QtyOnOrder is scheduled to arrive

%ProductSearchResult%

Name Type Description
ProductsMatched integer Total number of transactions matched
ProductsReturned integer Number of transactions returned in this result set
StartIndex integer The starting index used (defaults to 0)
Limit integer The max number transactions to return in each result set.
Product array An array Products for the matched criteria

%Receipt%

Name Type Description
ReceiptRefNum string Gateway assigned ID of Receipt. (Ignored when adding a receipt)
Name string Name of receipt (used to identify receipt)
Target string Type of receipt output (Email or Print)
Subject string Subject line of email (Only applicable if "Target" is "Email")
FromEmail string From email address (Only applicable if "Target" is "Email")
ContentType string Content types supported by receipt (HTML, Text or Both)
TemplateHTML string HTML version of template (Base-64 Encoded)
TemplateText string Text version of template (Base-64 Encoded)

%RecurringBilling%

Name Type Description
Schedule string Frequency of recurring billing schedule. Possible values include: disabled, daily, weekly, bi-weekly (every two weeks), monthly, bi-monthly (every two months), quarterly, bi-annually (every six months), annually.
Next string Date this customer will be billed next. Must be formatted Year-Month-Day (ie 2011-07-04)
Expire string Date this billing entry will be disabled.
NumLeft integer Number of transactions remaining in recurring billing cycle. (Overrides the Expire parameter)
Amount double Amount to be billed in each transaction.
Enabled boolean Notes whether customer is currently enabled for recurring billing.

%SearchParam%

Name Type Description
Field string Name of field you are searching.
Type string Search condition. Possible Values are:
- dneq -Does not Equal
- eq -Equals
- gt -Greater Than
- lt -Less Than
- gte -Greater Than or Equal To
- lte -Less Than or Equal To
- sw -Starts with
- ew -Ends with
- contains -contains
- dncontain -Does not Contain
- in -In List
- notin -Not in List
Value string Value to search on

%SyncLog%

Name Type Description
SyncPosition integer Sequential id of sync log entry
ObjectName string Object type that was changed (products, products_categories, customers, etc)
RefNum string Reference number for object that was changed (ProductRefNum, CustRefNum, etc)
ChangeDate string The date/time that the changed occurred on the gateway (all times in PST)
Action string The type of change that occurred (insert,update or delete)

%SystemInfo%

Name Type Description
ApiVersion string Version of the API
Environment string Production, Sandbox, or Staging
Datacenter string Location of the data-center
Time string Timestamp

%ShippingAddress%

Name Type Description
FirstName String Customer's First Name
LastName String Customer's Last Name
Company String Company or Organization Name
Street String Street Address Line 1
Street2 String Street Address Line 2
City String City
State String State or Province
Zip String Zip or Postal Code
Country String Country
Phone String Telephone Number
Fax String Fax Number
Email String Email Address

%TransactionObject%

Name Type Description
Status string Status of specified transaction.
TransactionResponse object Returns a TransactionResponse object containing the results of the transaction and all relevant data.
TransactionType string Type of transaction. (Sale, Credit, Void, AuthOnly, etc.)
CheckTrace object Tracking data for check transactions. Includes tracking number, effective posting date, date processed, date settled, date returned and bank notes.
DateTime string Date/time transaction was originally submitted.
AccountHolder string Name of the account holder.
Details object Transaction details: amount, clerk, currency, etc.
CreditCardData object CreditCardData. Required for credit card transactions.
CheckData object CheckData. Required for electronic check processing.
User string The username of the person who processed this transaction.
Source string The name of the source key that this transaction was processed under.
ServerIP string IP Address of the server that submitted the transaction to the gateway.
ClientIP string IP Address of client (if passed on from the server).
CustomerID string Customer ID
BillingAddress object Billing Address
ShippingAddress object Shipping Address
CustomFields array Array of FieldValue pairs. Additional transaction api fields (ie UMtimeout) can also be passed in via this array. Any field name starting with UM is assumed to be an api field and not a custom field.
LineItem array Array of line item details
LodgingDetails object Object which contains lodging details.

%TransactionRequestObject%

Name Type Description
Command string Processing Command. Possible values are: sale, credit, void, creditvoid, authonly, capture, postauth, check and checkcredit. Default is sale.
IgnoreDuplicate boolean Do not check for duplicate transaction. Set to "true" if you would like to override the duplicate transaction handling.
AuthCode string Original Authorization Code. Authorization Code obtained "offline" (ie telephone authorization). Only required for PostAuth.
RefNum string Original Transaction Reference Number. The RefNum received when a transaction was authorized via either the "sale" or "authonly" commands. Required for void and capture commands. Can also use TransKey here.
AccountHolder string Name of the account holder.
Details object Transaction details: amount, clerk, currency, etc.
CreditCardData object CreditCardData. Required for credit card transactions.
CheckData object CheckData. Required for electronic check processing.
ClientIP string IP Address of client.
CustomerID string Customer ID.
BillingAddress object Billing Address
ShippingAddress object Shipping Address
CustReceipt boolean True/False. True will cause a customer receipt to be sent.
CustReceiptName string Name of the receipt template to use. Defaults to the standard customer receipt.
RecurringBilling object RecurringBilling. Object describing if recurring billing cycle should be created if initial transaction is approved.
LineItem array Array of line item details
LodgingDetails object Object which contains lodging details.
CustomFields array Array of FieldValue pairs. Additional transaction api fields (ie UMtimeout) can also be passed in via this array. Any field name starting with UM is assumed to be an api field and not a custom field.
IfAuthExpired string Controls what will happen if the authorization has expired. Possible values are:
- Error will block the capture request
- ReAuth will attempt to reauthorize the funds
- Capture will ignore the authorization date and proceed with capture.

If left blank, Capture will be assumed. The amount of time between an authorization expires is controlled by the Expire Auths After setting.
AuthExpireDays string Sets number of days before an authorization expires.
ReleaseFunds boolean Set to true to release funds. Only used for voidTransaction.
IsRecurring boolean Flags a credit card transaction as a recurring payment when sent to the platforms for processing. This is not related to the RecurringBilling object above and it does not tie into the gateway's recurring billing system. Rather, this flag should be used by developers who are initiating the recurring transactions from within their own system and need to indicate that it is recurring.
Software string Free form string that can be used by the developer to record information about their software, version, build number or operating system details. Reported on the transaction detail screen, in custom reports or via api.
SaveCard boolean Set to "True" to tokenize card.

%TransactionResponse%

Name Type Description
TransKey string Transaction Reference Number This is the preferred Transaction Identifier (ALWAYS System Scoped)
RefNum string Transaction Reference Number (sometimes Merchant Scoped)
BatchRefNum string Batch Reference Number assigned by Gateway.
BatchKey string Batch Reference Number assigned by Gateway.
BatchNum string Batch Sequence Number
Result string Transaction Result (Approved, Declined, Error, etc)
ResultCode string Single character result code (A, D, or E)
AuthCode string Authorization Code
AuthAmount double Amount that was authorized. Could be less that Amount requested if AllowPartialAuth was true
RemainingBalance double Returns the balance remaining on some prepaid and stored value cards
AvsResultCode string AVS Result Code (1-3 characters)
AvsResult string Text Description of AvsResultCode
CardCodeResultCode string Card Code (CVV2) Verification Result Code (1 character)
CardCodeResult string Text Description of Card Code Result
CardLevelResultCode string List of codes can be found here.
CardLevelResult string Text Description of Card Level Result
CreditCardToken object This object describes a tokenized credit card.
ErrorCode integer Error Code (if transaction resulted in error)
CustNum string System assigned CustNum of stored customer record if one was used or created
CustKey string Customer Number (System assigned)
Error string Text Description of Error Code
AcsUrl string ACS Url for Verified by Visa or Mastercard Secure Code.
Payload string Payload for Verified by Visa or Mastercard Secure Code.
VpasResultCode string Vpas Result Code.
isDuplicate boolean If true, a duplicate transaction was detected and the response data returned is from original transaction.
ConvertedAmount double Transaction amount converted to new currency.
ConvertedAmountCurrency string Currency code for new currency.
ConversionRate double Rate used to convert transaction amount.
Status string Description of transaction status
StatusCode string Single character code for transaction status
ProfilerScore string Score generated by fraud profiler.
ProfilerResponse string Fraud profiler result: pass, warn, review. Based on score thresholds
ProfilerReason string Comma separated list of reason codes that contributed to the score.

%TransactionSearchResult%

Name Type Description
TransactionsMatched integer Total number of transactions matched
TransactionsReturned integer Number of transactions returned in this result set
ErrorsCount integer Total number of errors matched
DeclinesCount integer Total number of declines matched
SalesCount integer Total number of Sales matched
CreditsCount integer Total number of Credits matched
AuthOnlyCount integer Total number of AuthOnlys matched
VoidsCount integer Total number of Voids matched
SalesAmount float Total dollar amount of Sales matched
CreditsAmount float Total dollar amount of Credits matched
AuthOnlyAmount float Total dollar amount of AuthOnlys matched
VoidsAmount float Total dollar amount of Voids matched
ErrorsAmount float Total dollar amount of errors matched
DeclinesAmount float Total dollar amount of Declines matched
StartIndex integer The starting index used (defaults to 0)
Limit integer The max number transactions to return in each result set.
TransactionObject object An array TransactionObjects for the matched transactions

%TransactionSession%

Name Type Description
OrgID string Organization ID
SessionID string Unique session identifier