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.

SDK method namesSoap API method namesDescription
paymentPageSelectPaymentMerchant creates a redirect payment. Within the response the merchant will get a redirect url to the mpay24 payment page. On the payment page the customer can choose a payment method and finish the payment.
paymentAcceptPaymentMerchant can execute the payment directly by providing all payment relevant data.
paymentDetailsTransactionStatusReturns the status of a payment.
cancelManualReverseCancels a transaction that is not captured (billed) so far.
captureManualClearFinish a payment. This is only needed if the merchant does not want an automatic capture of the transaction.
listAuthorizationsListNotClearedReturns a list with all payments that are not captured so far.
refundManualCreditRefund a transaction to the customer.
paymentHistoryTransactionHistoryReturns the different states a payment went through
tokenCreatePaymentTokenCreates a token for Creditcard payments. Returns a url to the merchant that can be embedded on the merchants page to do PCI conform Creditcard payments.
listCustomersListProfilesReturns a list of payment data that is stored on the mpay24 system.
deleteCustomerDeleteProfileDeletes stored customer payment data.
createCustomerCreateCustomerCreates new customer payment data

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.

Payment typeBrandsClass
credit card paymentVisa, Mastercard, Diners, Amex, JCBCreditCardPaymentType
direct debit paymentsHobex, B4P, Atos, BillpayDirectDebitPaymentType
online banking paymentsEPS, Sofort, GiropayOnlineBankingPaymentType
paypal paymentsPaypalPaypalPaymentType
paybox paymentsPayboxPayboxPaymentType
paysafecard paymentsPaysafecardPaysafecardPaymentType
invoice paymentsBillpay, KlarnaInvoicePaymentType
installment paymentsBillpay, KlarnaInstallmentPaymentType

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.

ParameterTypeDescription
beginLongBegin at this position. Only needed if the list is very long and cannot be returned in one result set.
sizeLongHow many list elements should be returned.
sortFieldSortFieldSpecify the sorting field using the given Enumeration.
sortTypeSortTypeSpecify if the sorting should be ascending or descending using the given Enumeration.
listInProgressBooleanList also transactions that are being processed right now.
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.

ParameterTypeDescription
mPayTidBigIntegerUnique identifier for a payment
stateId (optional)BigIntegerNeeded for partial refunds of a partial capture
amount (optional)BigDecimalNeeded for partial refunds
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.

ParameterTypeDescription
customerIdStringMerchants customer identifier
expiredByDateReturns only profiles expired by the given date
beginLongBegin at this position. Only needed if the list is very long and cannot be returned in one result set.
sizeLongHow many list elements should be returned.
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);

createCustomer

Stores a customer payment profile at mPAY24 without executing a payment. This payment profile can be reused later for payments.

mpay24.createCustomer(getCustomer(customerId, "Xenia Wiesbauer"), getVisaTestData());

    protected Customer getCustomer(String customerId, String customerName) {
        Customer customer = new Customer();
        customer.setCustomerId(customerId);
        customer.setName(customerName);
        customer.setBirthdate(getDate("1960-07-07"));
        customer.setClientIp("127.0.0.1");
        customer.setEmail("[email protected]");
        customer.setGender(Gender.Male);
        customer.setPhoneNumber("01522113356");
        return customer;
    }

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