Transact Pro Gateway v3 Java client library

This library provide ability to make requests to Transact Pro Gateway API v3.

Installation

com.github.transactpro:gateway

Maven

<dependency>
<groupId>com.github.transactpro</groupId>
<artifactId>gateway</artifactId>
<version>2.0.2</version>
</dependency>

Gradle

implementation 'com.github.transactpro:gateway:2.0.2'

Documentation

This README provide introduction to the library usage.

Supported operations

Available operations:

• Transactions
  • CANCEL
  • DMS CHARGE
  • DMS HOLD
  • MOTO DMS
  • MOTO SMS
  • INIT RECURRENT DMS
  • RECURRENT DMS
  • INIT RECURRENT SMS
  • RECURRENT SMS
  • REFUND
  • REVERSAL
  • SMS
  • Credit
  • P2P
  • B2P
• Information
  • HISTORY
  • RECURRENTS
  • REFUNDS
  • RESULT
  • STATUS
  • LIMITS
• Verification
  • 3-D Secure enrollment
  • Complete card verification
• Tokenization
  • Create payment data token
• Callback processing
  • verify callback data sign
• Reporting
  • Get transactions report in CSV format

Basic usage

importcom.github.transactpro.gateway.Gateway;
importcom.github.transactpro.gateway.model.request.data.PaymentMethod;
importcom.github.transactpro.gateway.operation.transaction.Sms;
importcom.github.transactpro.gateway.model.exception.ResponseException;
importcom.github.transactpro.gateway.model.digest.exception.DigestMismatchException;
importcom.github.transactpro.gateway.model.digest.exception.DigestMissingException;
importcom.github.transactpro.gateway.model.request.data.Money;
importcom.github.transactpro.gateway.model.request.data.System;
importcom.github.transactpro.gateway.model.request.data.general.Customer;
importcom.github.transactpro.gateway.model.request.data.general.Order;
importcom.github.transactpro.gateway.model.request.data.general.customer.Address;
importcom.github.transactpro.gateway.model.response.PaymentResponse;
importcom.github.transactpro.gateway.model.response.constants.Status;
publicclassMain {
publicstaticvoidmain(String[] args) {
Gatewaygw = newGateway(
"xxxxxxxx-xxxxxxxx-xxxxxxxxxx",
"8XY0ujBrVSkNpLe",
"https://payment.gateway.com/v3.0"
);
Smssms = newSms();
Addressaddress = newAddress()
.setCity("Chalon-sur-Saône")
.setCountry("FR")
.setFlat("10")
.setHouse("10")
.setState("NA")
.setStreet("Rue Garibaldi")
.setZip("71100");
Moneymoney = newMoney()
.setAmount(100)
.setCurrency("EUR");
Orderorder = newOrder()
.setDescription("Payment")
.setId("Order ID")
.setMerchantId("some-user-ID-in-eshop-system")
.setMerchantReferringName("Test payment")
.setMerchantTransactionId("33")
.setMerchantUrl("https://domain.com/custom-url/")
.setRecipientName("John Smith");
Customercustomer = newCustomer()
.setEmail("test@test.domain")
.setBirthDate("01/00")
.setPhone("123456789")
.setBillingAddress(address)
.setShippingAddress(address); Systemsystem = newSystem()
.setUserIp("127.0.0.1");
PaymentMethodpaymentMethod = newPaymentMethod()
.setCardholderName("John Doe")
.setPan("4111111111111111")
.setCvv("123")
.setExpMmYy("09/31");
sms.setCustomer(customer)
.setPayment(paymentMethod)
.setMoney(money)
.setOrder(order)
.setSystem(system); try {
gw.process(sms);
PaymentResponseparsedSmsResponse = sms.getResponse().parse();
if (parsedSmsResponse.getError() != null && parsedSmsResponse.getError().getCode() != 0) {
// Process Gateway error
} elseif (parsedSmsResponse.getGw().getRedirectUrl() != null) {
// Redirect user to received URL
}
} catch (IOExceptione) {
// Do something with IOException
} catch (ValidationExceptione) {
// Do something with ValidationException
} catch (DigestMissingException | DigestMismatchExceptione) {
// Do something with digest errors
} catch (ResponseExceptione) {
// Do something with unexpected response exception (like unexpected format)
} catch (Exceptione) {
// Do something with unexpected error
} finally {
// Resultsjava.lang.System.out.println(sms.getResponse().getBody());
java.lang.System.out.println(sms.getResponse().getStatusCode());
java.lang.System.out.println(sms.getResponse().getHeaders());
}
}
}

Card verification

importcom.github.transactpro.gateway.model.request.data.command.CardVerificationMode;
importcom.github.transactpro.gateway.model.request.data.Command;
importcom.github.transactpro.gateway.operation.verify.VerifyCard;
// create a payment to init card verification processCommandcommand = newCommand().setCardVerification(CardVerificationMode.INIT);
sms.setCustomer(customer).setCommand(command);
// complete card verification passing gateway transaction ID from initial paymentVerifyCardverification = newVerifyCard().setDataGatewayTransactionId(gatewayTransactionId);
gw.process(verification);
System.out.println(operation.getResponse().getStatusCode() == 200 ? "SUCCESS" : "FAILURE");
// send a payment with flag to accept only verified cardsCommandcommand = newCommand().setCardVerification(CardVerificationMode.VERIFY);
sms.setCustomer(customer).setCommand(command);

Payment data tokenization

importcom.github.transactpro.gateway.model.request.data.command.PaymentMethodDataSource;
importcom.github.transactpro.gateway.operation.token.CreateToken;
// option 1: create a payment with flag to save payment dataCommandcommand = newCommand().setPaymentMethodDataSource(PaymentMethodDataSource.DATA_SOURCE_SAVE_TO_GATEWAY);
sms.setCommand(command);
// option 2: send "create token" request with payment dataCreateTokenoperation = newCreateToken();
Moneymoney = newMoney().setCurrency("EUR");
Orderorder = newOrder().setDescription("Payment");
PaymentMethodpaymentMethod = newPaymentMethod()
.setCardholderName("John Doe")
.setPan("4111111111111111")
.setExpMmYy("09/31");
operation.setPayment(paymentMethod).setMoney(money).setOrder(order);
// send a payment with flag to load payment data by tokenCommandcommand = newCommand()
.setPaymentMethodDataSource(PaymentMethodDataSource.DATA_SOURCE_USE_GATEWAY_SAVED_CARDHOLDER_INITIATED)
.setPaymentMethodDataToken("<initial gateway-transaction-id>");
sms.setCommand(command);

Using alternative payment methods

To use an alternative payment method (like Google Pay), send a received token AS-IS or data from a decrypted token.

// set a corresponding flag that indicates a token providerCommandcommand = newCommand().setPaymentMethodType(PaymentMethodType.PAYMENT_METHOD_TYPE_GOOGLE_PAY);
operation.setCommand(command);
// option 1: send received token AS-ISPaymentMethodpaymentMethod = newPaymentMethod().setToken('<token>');
operation.setPayment(paymentMethod);
// option 2: send data from decrypted tokenExternalTokenDataexternalTokenData = newExternalTokenData()
.setCryptogram("<cryptogram from token>") // if available
.setEci("<ECI from token>") // if available
.setTransStatus("<transStatus from token>") // available for Click to Pay
.setDsTransId("<dsTransId from token>") // available for Click to Pay
.setAcsTransId("<acsTransId from token>") // available for Click to Pay
.setCardHolderAuthenticated(decryptedToken.paymentMethodDetails.assuranceDetails.cardHolderAuthenticated); // for Google PayPaymentMethodpaymentMethod = newPaymentMethod()
.setPan("<card number>")
.setExpMmYy("<card expiry>")
.setCardHolderName("<cardholder name>") // if available
.setExternalTokenData(externalTokenData);
operation.setPayment(paymentMethod);

Callback validation

importcom.github.transactpro.gateway.model.digest.ResponseDigest;
importcom.github.transactpro.gateway.model.exception.ResponseException;
importcom.github.transactpro.gateway.model.response.CallbackResult;
importcom.github.transactpro.gateway.model.response.GatewayResponse;
ResponseDigestresponseDigest = newResponseDigest(signFromPost);
responseDigest.setOriginalUri(paymentOperation.getResponse().getDigest().getUri()); // optional, set if availableresponseDigest.setOriginalCnonce(paymentOperation.getResponse().getDigest().getCnonce()); // optional, set if availableresponseDigest.setBody(jsonFromPost);
responseDigest.verify("xxxxxxxx-xxxxxxxx-xxxxxxxxxx", "8XY0ujBrVSkNpLe");
CallbackResultparsedResult = GatewayResponse.fromJson(jsonFromPost, CallbackResult.class);
System.out.println(parsedResult.getResultData().getGw().getGatewayTransactionId());

Transactions report loading

importcom.github.transactpro.gateway.Gateway;
importcom.github.transactpro.gateway.model.response.CsvResponse;
importcom.github.transactpro.gateway.operation.reporting.Report;
// NB. Merchant GUID/secret must be used instead of account GUID/secret!Gatewaygw = newGateway(
"xxxxxxxx-xxxxxxxx-xxxxxxxxxx",
"8XY0ujBrVSkNpLe",
"https://payment.gateway.com/v3.0"
);
Reportoperation = newReport()
.setCreatedFrom(java.lang.System.currentTimeMillis() / 1000L - 86400L)
.setFinishedTo(java.lang.System.currentTimeMillis() / 1000L);
gw.process(operation);
Response<CsvResponse> responce = operation.getResponse();
CsvResponseparsedCsv = responce.parse();
for (CSVRecordrecord : parsedCsv) {
System.out.println(record.toMap());
}

Useful enumerators

com.github.transactpro.gateway.model.response.constants.ErrorCode - error codes com.github.transactpro.gateway.model.response.constants.Status - transaction statuses com.github.transactpro.gateway.model.response.constants.Enrollment - card 3-D Secure enrollment statuses com.github.transactpro.gateway.model.response.constants.CardFamily - card families

Customization

If you need to load an HTML form from Gateway instead of cardholder browser redirect, a special operation type may be used:

importcom.github.transactpro.gateway.model.response.PaymentResponse;
importcom.github.transactpro.gateway.operation.helpers.RetrieveForm;
PaymentResponseparsedSmsResponse = paymentOperation.getResponse().parse();
RetrieveFormretrieveFormOperation = newRetrieveForm(paymentResponse);
gw.process(retrieveFormOperation);
System.out.println(retrieveFormOperation.getResponse().getBody());

Requirements

• This library works with Java 8 or above.

Submit bugs and feature requests

Bugs and feature request are tracked on GitHub

License

This library is licensed under the MIT License - see the LICENSE file for details.