com.netbilling.direct
Class V3Client

java.lang.Object
  com.netbilling.net.NetworkClient
      com.netbilling.direct.V3Client

public class V3Client
extends NetworkClient

This is the main class used to execute transactions. Below is a complete example program which will executes a transaction with the server using bogus input request data.

        import com.netbilling.direct.V3Client;
        import com.netbilling.direct.V3Client.Request;
        import com.netbilling.direct.V3Client.Response;
        import com.netbilling.net.PreConnectionException;
        import com.netbilling.net.PostConnectionException;
        import com.netbilling.net.ServerException;

        V3Client client = new V3Client();
        Request in = new Request();
        Response out = new Response();
        
        client.setDebug(true);          // optional
        //client.theIdGenerator().setPerformanceMode(true);     // See IdGenerator documentation

        in.set (Request.ACCOUNT_ID,     "110006559149");        // Your account number
        in.set (Request.SITE_TAG,       "SITE1");               // Your site tag
        in.set (Request.AMOUNT,         "5.00");
        in.set (Request.TRAN_TYPE,      "A");                   // A: auth only, see Request documentation
        in.set (Request.PAY_TYPE,       "C");                   // C: credit card, see Request documentation
        in.set (Request.CARD_NUMBER,    "4444333322221194");
        in.set (Request.CARD_EXPIRE,    "0909");                // MMYY format
        in.set (Request.CARD_CVV2,      "999");
        in.set (Request.BILL_NAME1,     "Joe");
        in.set (Request.BILL_NAME2,     "Doe");
        in.set (Request.BILL_STREET,    "123 Big Street");
        in.set (Request.BILL_ZIP,       "55555");

        try {
            in.set (Request.TRANS_ID, client.obtainNewId());    // Recommended, see obtainNewId documentation
            boolean good = client.doTrans (in,out);     // perform transaction
            if (good) {
                System.out.println (":: STATUS: The transaction was successful");
                // more details available in Response object
            } else {
                System.out.println (":: STATUS: The transaction was declined");
                // more details available in Response object
            }
            System.out.println (":: AUTH_MSG: " + out.get(Response.AUTH_MSG));
            System.out.println (":: TRANS_ID: " + out.get(Response.TRANS_ID));
        }
        catch (PreConnectionException x) {
            // failed to connect to server, transaction not processed
            x.printStackTrace();
        }
        catch (PostConnectionException x) {
            // Connection to server lost, transaction may or may not have been processed.
            x.printStackTrace();
        }
        catch (ServerException x) {
            // the transaction failed, most likely due to incorrect input, the exception contains more details.
            x.printStackTrace();
        }
 

Nested Class Summary

static class	V3Client.Request This class defines a Request object, used to send transaction parameters to the server.
static class	V3Client.Response This class defines a Response object, used to obtain the transaction response from the server.

Field Summary

Fields inherited from class com.netbilling.net.NetworkClient

PROTOCOL_HTTP, PROTOCOL_HTTPS

Constructor Summary

V3Client()
Create instance object of this class.

Method Summary

boolean	doTrans(V3Client.Request input, V3Client.Response output) Execute a transaction with the server.
java.lang.String	obtainNewId() This method returns a unique transaction identifier, which you should send to the server as part of the Request objects.
void	setDebug(boolean yes) This function allows you to turn debugging to System.err on or off.
void	setProtocol(java.lang.String protocol) This function allows you to change the protocol used to submit your request to the server.
void	setServer(java.lang.String server) This function allows you to change the default server your request is submitted to.
IdGenerator	theIdGenerator() Get reference to the internal IdGenerator class that's used for obtaining new transaction ids.

Methods inherited from class com.netbilling.net.NetworkClient

getPort, getProtocol, getServer, getURL, setPath, setPort

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

V3Client

public V3Client()

Create instance object of this class. One instance should normally be shared by all threads, but make sure setServer() and setProtocol() are not called while anoter thread is using the class.

By default, encrypted an encrypted connection (HTTPS) is used. For testing purposes, an unencrypted (HTTP) connection can be forced by calling the setProtocol(PROTOCOL_HTTP).

See Also:

setProtocol(java.lang.String), setServer(java.lang.String)

Method Detail

setDebug

public void setDebug(boolean yes)

This function allows you to turn debugging to System.err on or off. Default is off.

Parameters:

yes - enable or disable debugging

setProtocol

public void setProtocol(java.lang.String protocol)
                 throws java.net.MalformedURLException

This function allows you to change the protocol used to submit your request to the server. it should be one of PROTOCOL_HTTP and PROTOCOL_HTTPS. Default is PROTOCOL_HTTP if you select PROTOCOL_HTTPS (SSL encryption) you will need to install the Java SSL package available from http://java.sun.com/products/jsse/.

Unencrypted HTTP is only supported for development and testing purposes. For production deployment, you must use encrypted HTTPS.

Overrides:

setProtocol in class NetworkClient

Parameters:

protocol - one of PROTOCOL_HTTP or PROTOCOL_HTTPS

Throws:

java.net.MalformedURLException

See Also:

NetworkClient.PROTOCOL_HTTP, NetworkClient.PROTOCOL_HTTPS

setServer

public void setServer(java.lang.String server)
               throws java.net.MalformedURLException

This function allows you to change the default server your request is submitted to.

Overrides:

setServer in class NetworkClient

Parameters:

server - server host name or IP address

Throws:

java.net.MalformedURLException

doTrans

public boolean doTrans(V3Client.Request input,
                       V3Client.Response output)
                throws PreConnectionException,
                       PostConnectionException,
                       ServerException

Execute a transaction with the server. Please see top of this class documentation for an example.

Parameters:

input - Request object sent to server

output - Response object returned from server (will be reinitialized)

Throws:

PreConnectionException

PostConnectionException

ServerException

See Also:

V3Client.Request, V3Client.Response

obtainNewId

public java.lang.String obtainNewId()
                             throws PreConnectionException

This method returns a unique transaction identifier, which you should send to the server as part of the Request objects.

This will enable you to later determine what happened to the transaction, even if you experience a network error or time-out while waiting for the transaction response.

Throws:

PreConnectionException

See Also:

Request#setTransId, IdGenerator.obtainNewId()

theIdGenerator

public IdGenerator theIdGenerator()

Get reference to the internal IdGenerator class that's used for obtaining new transaction ids. You may want to use this to change the default timeout for the IdGenerator (in milliseconds), or to activate performance mode for high speed applications.

Example:

client.theIdGenerator().setTimeout_ms(15000);
client.theIdGenerator().setPerformanceMode(true);

See Also:

IdGenerator