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, the scope is (ECHECKSELECT, interactive-debit).
When requesting a payin report, the scope is (ECHECKSELECT, 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 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/"; // URL to call the Interactive flow
	private static final String AUTH_URL = "https://staging.mazoomagateway.com/register/"; // URL to call the authentication flow
	private static final String CLIENT_ID = "DP-e1d62678-5777-4803-a1a5-8dea76e4940e"; // Replace with your provided Merchant client id
	private static final String SECRET = "52564E1779A4DF1A8D4764E1A2F79DA4"; // Replace with your provided Merchant secret
	private static final String APP_KEY = "7d931ce83c49fcd328b0d147ce49d59a3cc8274848a7304ed76bc072cbfc18b4"; // Replace with your provided app key

	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(); // Creating the call to our API to generate a API token and validate the transaction

		boolean async = args.length == 1 && "ASYNC".equalsIgnoreCase(args[0]); // Creates an true/false condition

		Interactive_Revised demo = new Interactive_Revised(); // Create the demo that will run either the synchronous or the asynchronous method

		// Determines which method to choose
		if (async) {
			demo.asyncDemo(client);
		}else {
			demo.syncDemo(client);
		}
	}

	public void syncDemo(ITransactionClient client) {
		// Initiate the interactive transaction synchronously
		try {
			System.out.println("Welcome to Instant Bank Transfer Redirection Page using the synchronous method. Please wait a moment and you will be redirected shortly...");
			TransactionResponse resp = client.transactionAsync(makeInteractivePayInRequestWithFluent()).get();
			// Opens a browser with the redirect URL to the Instant Bank Transfer Page
			Desktop.getDesktop().browse(new URI(resp.getTransactionUrl()));
		} catch (ExecutionException | URISyntaxException | IOException | InterruptedException e) {
			// Print any 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("Welcome to Instant Bank Transfer Redirection Page using the asynchronous method. Please wait a moment and you will be redirected shortly...");
			TransactionResponse response = client.transactionAsync(makeInteractivePayInRequestWithFluent()).get();
			// Opens a browser with the redirect URL to the Instant Bank Transfer Page
			Desktop.getDesktop().browse(new URI(response.getTransactionUrl()));
		} catch (InterruptedException | ExecutionException | URISyntaxException | IOException e) {
			// Print any 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 for a debitable transaction

		//Detail parameters
		EProduct PRODUCT = EProduct.ECHECKSELECT; // This will always be ECHECKSELECT
		String COUNTRY = "US"; // US is the only allowed value
		long AMOUNT = 3165; // Replaceable with any dollar amount, must be sent with no decimals
		String CURRENCY = "USD"; // Only the USD currency is supported
		String RETURN_URL = "https://us.mazooma.com/"; // Determines where the user is directed to after the transaction is completed, regardless of transaction result
		String MERCHANT_ID = "Develope"; // Replace with the provided Merchant ID
		String MERCHANT_USER_ID = "UIGE4"; // Replace with Merchant Customer ID
		String MERCHANT_TRAN_ID = System.currentTimeMillis() + "S"; // The required Unique Merchant transaction ID, changeable at any value. If the ID exists, our system will generate an error
		int MERCHANT_SUB_ID = 0; // Merchant Sub ID, typically 0 unless specificied differently
		String ADDRE = "45 Colonial Ave"; // The user's home  address
		String REGION = "NJ"; // The user's home state
		String CITY = "Patterson"; // The user's home city
		String ZIP = "07502"; // The user's home ZIP code
		String FIRST_NAME = "Alberta"; // The user's first name
		String MIDDLE_NAME = "R"; // The user's middle name
		String LAST_NAME = "Bobbethcharleson"; // The user's last name
		String DRIVER_LICENSE = "L123345"; // The user's driver's license
		String LICENSE_STATE = "NJ"; // The issued state of the driver's licenese
		String PHONE = "6738732314"; // The user's phone number
		String DATA = ""; // Used to pass extra data through
		String TRANSACTION_STATE = "NJ"; // The current state the user is intiating a deposit from  
		String LANGUAGE = "en_us"; // Language should always be English
		String IP = ""; // Replace with the IP that is intiating the payment redirect
		String FULL_NAME = FIRST_NAME + " " + LAST_NAME; // Creates the full name object by adding the first and last name
		String DOB = "1985-03-16"; // The user's date of birth
		String TOKEN = null; // Replace with a valid token received from a successful deposit or successful new bank withdrawal

		// Create a builder request with the product, country, deposit amount, currency and redirection URL
		InteractiveTransactionBuilder builder = InteractiveTransactionBuilder.debit(PRODUCT, COUNTRY, AMOUNT, CURRENCY, RETURN_URL); 

		// Create a merchant
		// Sets a merchant by specifying the merchant id, merchant user id, merchant transaction id, merchant transaction type (optional) and the merchant sub id (optional)
		Merchant merchant = MerchantBuilder.interactive(MERCHANT_ID, MERCHANT_USER_ID, MERCHANT_TRAN_ID, EMerchantTransType.E_SPORTS, MERCHANT_SUB_ID); 

 
		// Create a sender
		// Sets the sender of the customer, address, region, city, zip and country is required
		Contact sender = new ContactBuilder(ADDRE, REGION, CITY, ZIP, COUNTRY) 
				.name(FULL_NAME)
				.build();

		// Create a receiver
		// Sets the receiver of the customer, address, region, city, zip and country is required
		Contact receiver = new ContactBuilder(ADDRE, REGION, CITY, ZIP, COUNTRY) 
				.name(FIRST_NAME, MIDDLE_NAME, LAST_NAME)
				.build();

		// Create a consumer
		// To create a customer for interactive transaction, the date of birth is required
		Consumer consumer = ConsumerBuilder.interactive(LocalDate.parse(DOB)) 
				.driversLicense(DRIVER_LICENSE) // Optional - driver's license
				.driversLicenseState(LICENSE_STATE) // Optional - the issued state of the driver's license
				.phoneNumber(PHONE) // Optional - phone number
				// You must set a sender or receiver; at least one of each is required
				.sender(sender) // The sender object
				.receiver(receiver) // The receiver object
				.build();

		// Create a bank by specifying the bank information

		// To initiate a new bank deposit with no token, uncomment the line below
		BankInfo bankInfo = null;

		// To initiate a subsequent deposit with token, comment out the previous line and uncomment the line below
		// BankInfo bankInfo = BankInfoBuilder.bankWithToken(TOKEN).build();

		return builder.dataPassThrough(DATA) // Optional - used to pass extra data through, this will only be sent back in the transaction notification 
				.transactionRegion(TRANSACTION_STATE) // The current state the user is intiating a deposit from  
				.language(LANGUAGE) // Optional - language
				.originatorIp(IP)  // The IP address that is intiating the payment redirect 
				.merchant(merchant) // Merchant object
				.consumer(consumer) // Consumer object
				.bankInfo(bankInfo) // Bank info object
				.build(); // Builds the request
	}

	private TransactionRequest makeInteractivePayInRequestWithFluent() {
		

		// Detail parameters
		EProduct PRODUCT = EProduct.ECHECKSELECT; // This will always be ECHECKSELECT
		String COUNTRY = "US"; // US is the only allowed value
		long AMOUNT = 3165; // Replaceable with any dollar amount, must be sent with no decimals
		String CURRENCY = "USD"; // Only the USD currency is supported
		String RETURN_URL = "https://us.mazooma.com/"; // Determines where the user is redirected to after the transaction is completed, regardless of transaction result
		String MERCHANT_ID = "Develope"; // Replace with the provided Merchant ID
		String MERCHANT_USER_ID = "UIGE4"; // Replace with Merchant Customer ID
		String MERCHANT_TRAN_ID = System.currentTimeMillis() + "S"; // The required Unique Merchant transaction ID, changeable at any value. If the ID exists, our system will generate an error
		int MERCHANT_SUB_ID = 0; // Merchant Sub ID, typically 0 unless specified differently
		String ADDRE = "45 Colonial Ave"; // The user's home  address
		String REGION = "NJ"; // The user's home state
		String CITY = "Patterson"; // The user's home city
		String ZIP = "07502"; // The user's home ZIP code
		String FIRST_NAME = "Alberta"; // The user's first name
		String MIDDLE_NAME = "R"; // The user's middle name
		String LAST_NAME = "Bobbethcharleson"; // The user's last name
		String DRIVER_LICENSE = "L123345"; // The user's driver's license
		String LICENSE_STATE = "NJ"; // The issued state of the driver's licenese
		String PHONE = "6738732314"; // The user's phone number
		String DATA = ""; // Used to pass extra data through
		String TRANSACTION_STATE = "NJ"; // The current state the user is intiating a deposit from  
		String LANGUAGE = "en_us"; // Language should always be English
		String IP = ""; // Replace with the IP that is intiating the payment redirect
		String FULL_NAME = FIRST_NAME + " " + LAST_NAME; // Creates the full name object by adding the first and last name
		LocalDate DOB = LocalDate.of(1985, 3, 16); // The user's date of birth
		String TOKEN = null; // Replace with a valid token received from a successful deposit or successful new bank withdrawal


		return RequestBuilder.interactive(PRODUCT, COUNTRY) // Make an interactive transaction request
				.debit(AMOUNT, CURRENCY, RETURN_URL) // Specify the amount, currency and redirection page 
				.dataPassThrough(DATA) // Optional - used to pass extra data through, this will only be sent back in the transaction notification 
				.language(LANGUAGE) // Optional - language used during the deposit
				.transactionRegion(TRANSACTION_STATE) // The current state the user is intiating a deposit from  
				.originatorIp(IP) // The IP address that is intiating the payment redirect 
				.withMerchant(MERCHANT_ID, MERCHANT_USER_ID, MERCHANT_TRAN_ID) // Creates a merchant by specifying the merchant id, merchant user id and the merchant transaction id
				.transactionType(EMerchantTransType.CASINO) // Optional - Specifies the merchant transaction type
				.merchantSubId(MERCHANT_SUB_ID) // Optional - specifies the merchant sub id
				.and()
				.withConsumer(DOB) // Sets the customer's date of birth
				.driversLicense(DRIVER_LICENSE) // Optional - driver's license
				.driversLicenseState(LICENSE_STATE) // Optional - the issued state of the driver's license
				.phoneNumber(PHONE) // Optional - phone number
				// You must set a sender or receiver; at least one of each is required
				.sender(new ContactBuilder(ADDRE, REGION, CITY, ZIP, COUNTRY) // Sets the sender of the customer, address, region, city, zip and country is required
						.name(FULL_NAME) // utilizing the full name for contact name
						.build())
				.receiver(new ContactBuilder(ADDRE, REGION, CITY, ZIP, COUNTRY) // Sets the receiver of the customer, address, region, city, zip and country is required
						.name(FIRST_NAME, MIDDLE_NAME, LAST_NAME).build()) // Utilizing first name, middle name and last name for contact name
				.and()
				//.bankWithToken(TOKEN) // Uncomment this line and the bottom line to use token for returning bank deposit
				//.and()
				.build();
	}
}