createBatchUpload

Post a new batch of transactions to the gateway for processing.

Description

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
  • source
  • invoice
  • cardholder
  • ccnum
  • ccexp
  • avsstreet
  • avszip
  • cvc
  • amount
  • tax
  • description
  • ponum
  • orderid
  • custid
  • billing_company
  • billing_fname
  • billing_lname
  • billing_street
  • billing_street2
  • billing_city
  • billing_state
  • billing_country
  • billing_zip
  • billing_phone
  • shipping_company
  • shipping_fname
  • shipping_lname
  • shipping_street
  • shipping_street2
  • shipping_city
  • shipping_state
  • shipping_zip
  • shipping_country
  • shipping_phone
  • email
  • checknum
  • vcrouting
  • vcaccount
  • vcssn
  • vcdl
  • vcdlstate

See also pauseBatchUpload, getBatchUploadStatus, runBatchUpload

Syntax

BatchUploadStatus createBatchUpload ( ueSecurityToken Token, string FileName, boolean AutoStart, string Format, string Encoding, string Fields, string Data, boolean OverrideDuplicates )

Arguments

Type Name Description
ueSecurityToken Token Merchant security token: used to identify merchant and validate transaction.
string FileName Name of upload file. Can also be used to store a reference ID.
boolean AutoStart 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.
string Format The format of the data upload. Currently supported data formats are: csv, tab and xml.
string Encoding Data encoding method used. Supported methods include: 7bit, base64 and uuencode.
string Fields Fields being uploaded. These fields must be listed in the same order they appear in the data
string Data Transaction data being uploaded.
boolean OverrideDuplicates 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.

Return Value

Type Description
BatchUploadStatus Returns the result of the batch upload.

Examples

PHP

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

    <?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();

    }

    ?>

VB.net

This example is using Me.getSecurityToken() to build the token object. The source for this function can be found on the ueSecurityToken page.

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)

.NET C

            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

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

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>

Java

This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to the Java JAX-WS Howto.

    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());
        }