Client Implementation


A guide to posting transaction and report requests, using the Mazooma Java client library.


Transaction overview

Transaction flow direction

Transactions can flow in one of two directions:

  1. From the Consumer to the Merchant. This is referred to as a payin or debit transaction. In this type of transaction, the Consumer is transferring funds to the Merchant.
  2. From the Merchant to the Consumer. This is referred to as a payout or credit transaction. In this type of transaction, the Merchant is transferring funds to the Consumer.

Transaction method

Transctions can be processed interactively or directly:

  • Interactive transactions: Interactive transactions are initiated from the Consumer’s web browser and may require the Consumer to enter their banking information.
  • Direct transactions: Direct transactions are server to server requests and don’t require the Consumer to interact with their web browser.

Setting up client libraries

Before you can post transaction and report requests, you need to set up the client libraries that you’ll use for your implementation.

Download the files

  1. Open https://bitbucket.org/mazoomapayments/single-api-client.
  2. Clone the singleAPIclient repository.
  3. Download the applicable jar files from the Artifacts section.
  4. Move the jar files to a folder named jars.
  5. Add the jars folder to your project’s class path.

About the Java clients

Each API Java client, transaction and reporting, is packaged as a single jar file that includes the implementation and all dependencies. Some shared code and libraries are included in both jars.

The terms below are used in both libraries, with some shared and some different meaning:

Term Transaction API Reporting API Both APIs
Client ID The product Merchant must belong to the client ID. If a Merchant is specified as a report condition, the Merchant’s access is checked by client ID. If the Merchant is not specified, they are set as the default Merchant the client owns. Security checking. Verified with a token.
App key Each service call has only one scope.

For example, when making an interactive payin with eCheck Select, the scope is (ECHECKSELECT, interactive-debit).
A report request may contain multiple scopes, depending on the specified products and transaction types.

For example, when requesting a payin report, the scope is (ECHECKSELECT, report-debit). When requesting payin report for all products, the scopes are (<All products the client can access>, report-debit). When neither product nor transaction type is specified, the scopes are (<All products the client can access>, <All report types>).
Define the access scope of an app. This includes the product as well as the action that can be performed on the product.
Client library URLs

The Mazooma Java client libraries require the following URLs:

Client AUTH_URL BASE_URL
Transaction https://staging.mazoomagateway.com/register/ https://staging.mazoomagateway.com/transaction/
Reporting https://staging.mazoomagateway.com/register/ https://staging.mazoomagateway.com/report

Initiating transactions

All Mazooma transaction API calls using the Java client library involve creating a client factory and building an API call. API calls can be built either fluently or with buiders depending on the developer’s preference, however the both methods serve the same function.

import com.pgw.gatewayapi.transaction.ClientFactory;
import com.pgw.gatewayapi.transaction.ITransactionClient;
import com.pgw.gatewayapi.transaction.model.*;
import com.pgw.gatewayapi.transaction.model.request.TransactionRequest;
import com.pgw.gatewayapi.transaction.model.request.builder.*;
import com.pgw.gatewayapi.transaction.model.response.TransactionResponse;

import java.awt.*;
import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.time.LocalDate;
import java.util.concurrent.ExecutionException;


public class Interactive_Revised {

	private static final String BASE_URL = "https://staging.mazoomagateway.com/transaction/";
	private static final String AUTH_URL = "https://staging.mazoomagateway.com/register/";
	private static final String CLIENT_ID = "DP-e1d62678-5777-4803-a1a5-8dea76e4940e";
	private static final String SECRET = "52564E1779A4DF1A8D4764E1A2F79DA4";
	private static final String APP_KEY = "7d931ce83c49fcd328b0d147ce49d59a3cc8274848a7304ed76bc072cbfc18b4";

	public static void main(String[] args) {
		ClientFactory factory = new ClientFactory(BASE_URL, AUTH_URL, CLIENT_ID, SECRET, APP_KEY); //API token call
		//factory.setTimeout(TIME_OUT); // Uncomment to set the network timeout in seconds. The default is 60.
		//factory.setMaxThreads(MAX_THREADS); // Set the maximum number of requests to execute concurrently. The default is 64.
		ITransactionClient client = factory.create();

		boolean async = args.length == 1 && "ASYNC".equalsIgnoreCase(args[0]);

		Interactive_Revised demo = new Interactive_Revised();
		if (async) {
			demo.asyncDemo(client);
		}else {
			demo.syncDemo(client);
		}
	}

	public void syncDemo(ITransactionClient client) {
		// Initiate the transaction synchronously
		try {
			System.out.println("Welcome to eCS Redirection Page using the synchronous method. Please wait a moment and you will be redirected shortly...");
			TransactionResponse resp = client.transactionAsync(makeInteractivePayInRequestWithFluent()).get();
			Desktop.getDesktop().browse(new URI(resp.getTransactionUrl()));
		} catch (ExecutionException | URISyntaxException | IOException | InterruptedException e) {
			//print error that occurred
			System.out.println("The following error occured while using the synchronous method:");
			e.printStackTrace();
		}
	}

	public void asyncDemo(ITransactionClient client) {
		//Initiate the transaction asynchronously
		try {
			System.out.println("Hi! Welcome to eCS Redirection Page using the asynchronous method. Please wait a moment and you will be redirected shortly...");
			TransactionResponse response = client.transactionAsync(makeInteractivePayInRequestWithFluent()).get();
			Desktop.getDesktop().browse(new URI(response.getTransactionUrl()));
		} catch (InterruptedException | ExecutionException | URISyntaxException | IOException e) {
			//print error that occurred
			System.out.println("The following error error occured while using the asynchronous method:/n");
			e.printStackTrace();
		}
	}


	private TransactionRequest makeInteractivePayInRequestWithBuilder() {
		// create an interactive transaction builder for debitable transaction

		//details
		EProduct PRODUCT = EProduct.ECHECKSELECT;
		String COUNTRY = "US";
		long AMOUNT = 3165; //replace with dollar amount
		String CURRENCY = "USD";
		String RETURN_URL = "https://www.paramountcommerce.com";
		String MERCHANT_ID = "Develope"; //replace with Merchant ID
		String MERCHANT_USER_ID = "UING4"; //replace with Merchant Transaction ID
		String MERCHANT_TRAN_ID = System.currentTimeMillis() + "S";
		int MERCHANT_SUB_ID = 0;
		String ADDRE = "45 Colonial Ave";
		String REGION = "NJ";
		String CITY = "Patterson";
		String ZIP = "07502";
		String FIRST_NAME = "Thompson";
		String MIDDLE_NAME = "R";
		String LAST_NAME = "Bobbethcharleson";
		String DRIVER_LICENSE = "L123345";
		String LICENSE_STATE = "NJ";
		String DATA = "";
		String TRANSACTION_STATE = "NJ";
		String LANGUAGE = "en_us";
		String IP = ""; //replace with your computer IP
		String FULL_NAME = FIRST_NAME + " " + LAST_NAME;
		String DOB = "1985-03-16";
		String TOKEN = null; //replace with a valid token 

		InteractiveTransactionBuilder builder = InteractiveTransactionBuilder.debit(PRODUCT, COUNTRY, AMOUNT, CURRENCY, RETURN_URL);

		// create a merchant
		Merchant merchant = MerchantBuilder.interactive(MERCHANT_ID, MERCHANT_USER_ID, MERCHANT_TRAN_ID, EMerchantTransType.E_SPORTS, MERCHANT_SUB_ID);


		// create a sender
		Contact sender = new ContactBuilder(ADDRE, REGION, CITY, ZIP, COUNTRY)
				.name(FULL_NAME)
				.build();

		// create a receiver
		Contact receiver = new ContactBuilder(ADDRE, REGION, CITY, ZIP, COUNTRY)
				.name(FIRST_NAME, MIDDLE_NAME, LAST_NAME)
				.build();

		Consumer consumer = ConsumerBuilder.interactive(LocalDate.parse(DOB)) // initiate a customer for interactive transaction, the date of birth is required
				.driversLicense(DRIVER_LICENSE) // optional - driver's license
				.driversLicenseState(LICENSE_STATE) // optional - the issue state of the driver's license
				// sender or receiver at least one of each needs to be set
				.sender(sender)
				.receiver(receiver)
				.build();

		// create a bank by specifying the bank information

		//to use the acquire flow with no token, uncomment the line below
		BankInfo bankInfo = null;

		//to use the acquire flow with token, comment out the previous line and uncomment the line below
		//BankInfo bankInfo = BankInfoBuilder.bankWithToken(TOKEN).build();

		return builder.dataPassThrough(DATA) // optional - extra data fields
				.transactionRegion(TRANSACTION_STATE)
				.language(LANGUAGE) // optional - language
				.originatorIp(IP) 
				.merchant(merchant)
				.consumer(consumer)
				.bankInfo(bankInfo)
				.build();
	}

	private TransactionRequest makeInteractivePayInRequestWithFluent() {
		//details
		EProduct PRODUCT = EProduct.ECHECKSELECT;
		String COUNTRY = "US";
		long AMOUNT = 2265; //replace with dollar amount
		String CURRENCY = "USD";
		String RETURN_URL = "https://www.paramountcommerce.com";
		String MERCHANT_ID = "Develope"; //replace with Merchant ID
		String MERCHANT_USER_ID = "UINTK1"; // Merchant user ID
		String MERCHANT_TRAN_ID = System.currentTimeMillis() + "A";
		int MERCHANT_SUB_ID = 0;
		String ADDRE = "45 Colonial Ave";
		String REGION = "NJ";
		String CITY = "Patterson";
		String ZIP = "07502";
		String FIRST_NAME = "Carter";
		String MIDDLE_NAME = "";
		String LAST_NAME = "Bobbethcharleson";
		String DRIVER_LICENSE = "L123345";
		String LICENSE_STATE = "NJ";
		String DATA = "";
		String TRANSACTION_STATE = "NJ";
		String LANGUAGE = "en_us";
		String IP = "";//replace this with your computer IP
		String FULL_NAME = FIRST_NAME + " " + LAST_NAME;
		LocalDate DOB = LocalDate.of(1985, 3, 16);
		String TOKEN = ""; //replace with a valid token

		return RequestBuilder.interactive(PRODUCT, COUNTRY) // make an interactive transaction request
				.debit(AMOUNT, CURRENCY, RETURN_URL) // make a debit transaction, the transaction amount, currency and return url is required
				.dataPassThrough(DATA) // optional - extra data fields
				.language(LANGUAGE) // optional - language
				.transactionRegion(TRANSACTION_STATE) // optional - the region where the transaction takes place
				.originatorIp(IP) // optional - the orginal ip address where the transaction is initiated
				.withMerchant(MERCHANT_ID, MERCHANT_USER_ID, MERCHANT_TRAN_ID) // set merchant, merchant id, use id and transaction id is required
				.transactionType(EMerchantTransType.CASINO) // optional - merchant transaction type
				.merchantSubId(MERCHANT_SUB_ID) // optional - merchant sub id
				.and()
				.withConsumer(DOB) // set customer, the date of birth is required
				.driversLicense(DRIVER_LICENSE) // optional - driver's license
				.driversLicenseState(LICENSE_STATE) // optional - the issue state of the driver's license
				// sender or receiver at least one of each needs to be set
				.sender(new ContactBuilder(ADDRE, REGION, CITY, ZIP, COUNTRY) // set the sender of the customer, address, region, city, postalcode and country is required
						.name(FULL_NAME) // use full name for contact name
						.build())
				.receiver(new ContactBuilder(ADDRE, REGION, CITY, ZIP, COUNTRY) // set the receiver of the customer, address, region, city, postalcode and country is required
						.name(FIRST_NAME, MIDDLE_NAME, LAST_NAME).build()) // use first name, middle name and last name for contact name
				.and()
				.bankWithToken(TOKEN) // use access token for bank info
				.and()
				.build();
	}
}