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 names

Soap API method names

Description

paymentPage

SelectPayment

Merchant 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.

payment

AcceptPayment

Merchant can execute the payment directly by providing all payment relevant data.

paymentDetails

TransactionStatus

Returns the status of a payment.

cancel

ManualReverse

Cancels a transaction that is not captured (billed) so far.

capture

ManualClear

Finish a payment. This is only needed if the merchant does not want an automatic capture of the transaction.

listAuthorizations

ListNotCleared

Returns a list with all payments that are not captured so far.

refund

ManualCredit

Refund a transaction to the customer.

paymentHistory

TransactionHistory

Returns the different states a payment went through

token

CreatePaymentToken

Creates 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.

listCustomers

ListProfiles

Returns a list of payment data that is stored on the mpay24 system.

deleteCustomer

DeleteProfile

Deletes stored customer payment data.

createCustomer

CreateCustomer

Creates 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 type

Brands

Class

credit card payment

Visa, Mastercard, Diners, Amex, JCB

CreditCardPaymentType

direct debit payments

Hobex, B4P, Atos, Billpay

DirectDebitPaymentType

online banking payments

EPS, Sofort, Giropay

OnlineBankingPaymentType

paypal payments

Paypal

PaypalPaymentType

paybox payments

Paybox

PayboxPaymentType

paysafecard payments

Paysafecard

PaysafecardPaymentType

invoice payments

Billpay, Klarna

InvoicePaymentType

installment payments

Billpay, Klarna

InstallmentPaymentType

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.

Parameter

Type

Description

begin

Long

Begin at this position. Only needed if the list is very long and cannot be returned in one result set.

size

Long

How many list elements should be returned.

sortField

SortField

Specify the sorting field using the given Enumeration.

sortType

SortType

Specify if the sorting should be ascending or descending using the given Enumeration.

listInProgress

Boolean

List 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.

Parameter

Type

Description

mPayTid

BigInteger

Unique identifier for a payment

stateId (optional)

BigInteger

Needed for partial refunds of a partial capture

amount (optional)

BigDecimal

Needed 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.

Parameter

Type

Description

customerId

String

Merchants customer identifier

expiredBy

Date

Returns only profiles expired by the given date

begin

Long

Begin at this position. Only needed if the list is very long and cannot be returned in one result set.

size

Long

How 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;
    }