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 .jar and example .java
usaepayapi-jaxws-1.6.5.jar.zip	1.6.5	02/26/2019	USAePayAPI-jaxws-1.6.5.jar only
java-11-dependencies.zip	1.0	02/26/2019	Dependencies that must be loaded when using Java versions 11 and up.

Using Library

Step 1: Import com.usaepay.api.jaxws Classes

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:

    import com.usaepay.api.jaxws.*;

Please Note: If you are using Java versions 11 and up, be sure to load the dependencies file in the Downloads section above.

Step 2: Instantiate client Object

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:

    // Instantiate client for production
    UeSoapServerPortType client = usaepay.getClient();

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).

    // Instantiate client for sandbox
    UeSoapServerPortType client = usaepay.getClient("sandbox.usaepay.com");

Step 3: Generate Security Token

A "token" object (of type UeSecurityToken) is required by all soap methods in the USAePay API. It is used to identify the merchant.

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

Step 4: Calling a Soap Method

Soap methods are called using the client object. Below is an example for calling the runSale method. For further examples see the soap api documentation.

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

Additional Documentation

For additional documentation please see the main Soap API v1.6 Documentation. It includes a description of all methods and their parameters as well as examples for the java library.

For questions please email integrations@usaepay.com