SDK for Java
SDK for Java is a software development kit for development of web services which are capable of integrating with the Monetix-based payment solutions to perform purchases by using Payment Page. This section describes how to use SDK for Java to build purchase experience from inside of your web service.
SDK for Java is compatible with Java SE Development Kit 8 or higher. You can download SDK for Java from GitHub: https://github.com/trxhosts/paymentpage-sdk-java.
What can I do with SDK for Java?
- Calculate signature and generate request for opening the Payment Page payment form
- Check callback signatures and extract payment details from callbacks
What's inside?
- Libraries for development and automated testing
- Code samples in Java
Using SDK for Java
- Make sure you have you have ready your merchant ID and secret key obtained from Monetix.
- If your company has never obtained any ID or secret key from Monetix, you need to submit an application for connecting to Monetix.
- If your company already has an ID and a secret key to sign messages obtained from Monetix, you need to notify the Monetix technical support specialists that you want to use SDK for Java and consult with the customer support on how to arrange a test run.
- Integrate the Monetix payment solution in your web service:
- Install the SDK for Java libraries into a directory inside your web service project.
- Import the libraries you need into your web service application.
- Test and put your web service in production mode.
- Request test card numbers and test project ID from Monetix, debug and test your web service.
- Once testing is complete, request your production project ID from Monetix and put your web service in production mode.
With any questions regarding usage of SDK for Java contact the Monetix technical support specialists at support@monetix.pro.
Installing and importing libraries
You can install the SDK for Java libraries manually or by using automated procedures supported by the development environment you use.
The following steps describe how to manually install the SDK for Java libraries.
- Download SDK for Java and pack the SDK files into a JAR file.
- If your project directory does not contain a libs directory, create one and move the JAR file into the libs directory.
- Import the file into your web service project by using the procedures pertinent to your development environment.
Opening payment form
Payment form invocation request consists of a set of parameters, which are signed to secure the data transmitted to Monetix. SDK for Java allows you to seamlessly sign parameters and generate requests. To open the Payment Page payment form by using SDK for Java do the following:
- Create an instance of the
Payment
class and specify payment details.Payment payment = new Payment('186', "pid_1555943554067"); // Project ID and payment ID // Payment ID must be unique within your project scope payment .setParam(Payment.PAYMENT_AMOUNT, 1001) // Amount in minor currency units .setParam(Payment.PAYMENT_CURRENCY, "EUR"); // Currency as per ISO-4217 alpha-3 .setParam(Payment.PAYMENT_DESCRIPTION, "Test payment"); // Payment description (optional)
All the parameters in this example are required to perform any payment. You can also use any optional parameters available for Payment Page. For more information about the Payment Page invocation parameters, see Payment Page invocation parameters.
- Create a
gate
instance and initiate it with the secret key you obtained from the Monetix technical support specialists. The secret key is required to sign invocation requests.Gate gate = new Gate("<secret_key>"); // Secret key you obtained from technical support service
- Generate payment form invocation request:
String paymentUrl = gate.getPurchasePaymentPageUrl("<pp_host>", payment);
Correct payment form invocation request contains payment parameters and signature (abbreviated):
https://paymentpage.trxhost.com/payment?signature=OEKRlLXKStyo ...%3D%3D&payment_id=1555943554067...123
- Use the request in your web service code to open the payment form.
Here is an example of generating a URL for opening an English payment form. The payment method selection page includes detailed payment information including amount, currency and short payment description.
Payment payment = new Payment('186', "pid_1555943554067"); // Project ID and payment ID // Payment ID must be unique within your project scope payment .setParam(Payment.PAYMENT_AMOUNT, 1001) // Amount in minor currency units .setParam(Payment.PAYMENT_CURRENCY, "EUR"); // Currency .setParam(Payment.PAYMENT_DESCRIPTION, "Test payment"); // Payment description .setParam(Payment.LANGUAGE_CODE, ("en"); // Language code to use in payment form Gate gate = new Gate("mySecret"); // Secret key String paymentUrl = gate.getPurchasePaymentPageUrl("example.com", payment); // Complete request with signature
Parsing callbacks
The Monetix payment platform sends payment results to the callback URL you specified when connecting to Monetix. Callback is an HTTP POST request that contains response data in JSON format. To extract payment information from JSON string do the following:
- Create an instance of
Gate
with the secret key, if you did not it earlier.Gate gate = new Gate("<secret_key>");
-
Create an instance of
Callback
by using the JSON string from the callback obtained from Monetix:Callback callback = gate.handleCallback(data);
-
Use methods for extracting callback information. You can get either full payment information or request specific payment parameters:
callback.getPaymentId(); // Getting payment ID callback.getPaymentStatus(); // Getting payment status callback.getPayment(); // Getting payment body
By using SDK for Java, you can automatically check validity of callback signature. Below, you will find an example of callback that includes signature and payment results.
{
"project_id": 186, // Project ID
"payment": { // Payment details
"id": "pid_1555943554067", // Payment ID
"type": "purchase", // Payment type
"status": "success", // Payment status
"date": "2018-08-28T09:11:28+0000", // Payment date and time
"method": "card", // Payment method
"sum": { // Payment amount and currency
"amount": 1000,
"currency": "EUR"
},
"description": "Test payment" // Payment description
},
"account": { // Payment instrument details
"number": "431422******0056",
"token": "9cb38282187b7a5b5b91b5814c6b814162741b29c0c486fbbc500cd451abb8b2",
"type": "visa",
"card_holder": "ADA LOVELACE",
"id": 778804,
"expiry_month": "11",
"expiry_year": "2021"
},
"operation": { // The last operation within payment
"id": 17839000001150, // Operation ID
"type": "sale", // Operation type
"status": "success", // Operation status
"date": "2018-08-28T09:11:28+0000", // Operation date and time
"created_date": "2018-08-28T09:10:50+0000",
"request_id": "2c8af331519833f2c96c4a1aaf60edfcffb...", // Request ID
"sum_initial": { // Initial payment amount and currency
"amount": 1000,
"currency": "EUR"
},
"sum_converted": {
// Payment amount and currency as per applicable project conversion rules
"amount": 1000,
"currency": "EUR"
},
"provider": { // Payment details in payment system
"id": 6,
"payment_id": "15354474886323",
"date": "2018-02-07T08:34:24+0000",
"auth_code": "563253",
"endpoint_id": 6
},
"code": "0", // Unified response code
"message": "Success", // User-readable response code
"eci": "05" // ECI code, result of 3-D Secure check
},
"signature": "22YlUIIgoppli/JX8w5F5+c2h12RXi81WLmgDx..." // Signature
}