Java SDK

Maven integration

The SDK can be downloaded from the central maven repository. The dependency for the Java mPAY24 SDK is the following:

<!-- https://mvnrepository.com/artifact/com.mpay24.payment/mpay24-payment-sdk -->
<dependency>
    <groupId>com.mpay24.payment</groupId>
    <artifactId>mpay24-payment-sdk</artifactId>
    <version>1.9.1.0</version>
</dependency>

mpay24 class

The Mpay24 class is instantiated using your merchant id, your soap password and the environment you are connecting to (TEST or PRODUCTION):

Mpay24 mpay24 = new Mpay24("93975", "xxx", Environment.TEST);

SDK calls

We decided to use payment industry well known method names within the SDK instead the ones available within the Soap API. As the rest of the documentation uses the names within the API we provide a mapping for the names.

payment page (redirect integration)

The easiest possible payment is to provide a PaymentRequest and forward the end customer to the payment page using the redirectLocation (see Unit Test testMostSimpleRedirectPayment):

Payment response = mpay24.paymentPage(getTestPaymentRequest());
String redirectURL = response.getRedirectLocation();
  
protected PaymentRequest getTestPaymentRequest() {
		PaymentRequest paymentRequest = new PaymentRequest();
		paymentRequest.setAmount(new BigDecimal(1));
		paymentRequest.setTransactionID("1");
		return paymentRequest;
}

Beside the mandatory PaymentRequest there are optional parameter that can be provided like Customer, ShoppingCart and StylingOptions.

Payment response = mpay24.paymentPage(getTestPaymentRequest(), getCustomerWithAddress(), getShoppingCart(), getStylingOptions(Template.MODERN));

payment

Payment is used if the merchant wants the customer to enter the payment data on the merchants webpage. The merchant then sends all payment related data to mpay24 who executes the payment on behalf of the merchant. The merchant can also provide additional parameter like Customer, Address, ShoppingCart.

Payment response = mpay24.payment(getTestPaymentRequest(), getVisaTestData());

	protected PaymentTypeData getVisaTestData() throws ParseException {
		CreditCardPaymentType paymentType = new CreditCardPaymentType();
		paymentType.setPan("4444333322221111");
		paymentType.setCvc("123");
		paymentType.setExpiry(getCreditCardMonthYearDate("12/2016"));
		paymentType.setBrand(CreditCardPaymentType.Brand.VISA);
		return paymentType;
	}

Depending on the payment type the merchant need to provide different payment data. Within the table you will find the class to use depending on the type of payment that is executed.

paymentDetails

You can retrieve the status for a single payment at any time using the paymentStatus method. As parameter to query a payment status you can either use the Payment object that was returned by the SDK.
Alternative is a method that uses either the mpaytid which is the unique transaction identifier provided by mpay24 or the transaction id provided by the merchant.

Payment paymentDetails = mpay24.paymentDetails(payment);

Return paymentStatus using the mpaytid:

Payment paymentDetails = mpay24.paymentDetails(new BigInteger(1));

Return paymentStatus using the merchant specified transaction identifier:

Payment paymentDetails = mpay24.paymentDetails("83423984");

cancel

Cancelling a payment after authorization. This is only possible if no auto capture is enabled.

mpay24.cancel(payment);

Cancel payment using the mpaytid:

mpay24.cancel(new BigInteger(1));

capture

Finishing a payment after authorization. This is only possible if no auto capture is enabled. This can also be a partial capture if the amount is smaller than the payment amount.

payment = mpay24.capture(payment);

Finish a payment using the mpaytid:

mpay24.capture(payment.getmPayTid());

It is also possible to capture only part of the payment by providing the amount to be captured. Note: The amount must be smaller or equal to the payment amount.

mpay24.capture(payment.getmPayTid(), new BigDecimal(0.1))

listAuthorizations

Returns a list of payments that are not finished (only authorized) so far. The payments need to be captured or canceled.

List<Payment> paymentList = mpay24.listAuthorizations(0, 100, null, null, false);

refund

Refunds a finished payment to the customer. This can also be a partial refund if the amount is smaller than the payment amount.

Refund refund = mpay24.refund(payment);

Refund using the mpaytid:

Refund refund = mpay24.refund(new BigInteger(1));

Partial refund using the mpaytid and amount:

Refund refund = mpay24.refund(new BigInteger(1), new BigDecimal(0.1));

Partial refund for a partial capture using mpaytid, stateid and amount. The stateid is returned if partial capture is done. So a partial capture can have multiple refunds.

Refund refund = mpay24.refund(new BigInteger(1), new BigInteger(1), new BigDecimal(1.0);

paymentHistory

Returns all states a payment went through. A better understanding of the different states can be found at https://docs.mpay24.com/v1.5/docs/transaction-states

List<Payment> paymentHistory = mpay24.paymentHistory(payment);

token

Creates a payment token for a credit card payment and returns the url to the iFrame.

Token token = mpay24.token(getTestTokenRequest("EN"));
// open link and enter Creditcard details
Payment response = mpay24.payment(getTestPaymentRequest(), new TokenPaymentType(tokentoken.getToken()));

listCustomers

Returns a list of all stored customer payment data. This is useful to get an overview for which customer payment details are stored on the mpay24 system.

List<PaymentData> customerList = mpay24.listCustomers(customerId, null, null, null);

deleteCustomer

Delete stored payment data for a customer. Provide either the profile id or the customer id.

mpay24.deleteCustomer(customerId, null);