SDK for Java

SDK for Java is a software development kit for development of web services which are capable of integrating with the Benker 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.

What can I do with SDK for Java?

SDK for Java allows you to do the following:

Calculate signature and generate an URL for opening the Payment Page.
Check callback signatures and extract payment details from callbacks

What's inside?

SDK for Java contains the following:

Libraries for development and automated testing
Code samples in Java

Using SDK for Java

To start using SDK for Java you need to complete the following tasks:

Make sure you have you have ready your merchant ID and secret key obtained from Benker.
1. If your company has never obtained any ID or secret key from Benker, you need to submit an application for connecting to the Benker payment platform.
2. If your company already has an ID and a secret key to sign messages obtained from Benker, you need to notify the Benker technical support specialists that you want to use SDK for Java and consult the customer support on how to arrange a test run.
Integrate the Benker payment solution in your web service:
1. Install the SDK for Java libraries into a directory inside your web service project.
2. Import the libraries you need into your web service application.
Test and put your web service in production mode.

With any questions regarding the use of SDK for Java contact the Benker technical support specialists at help@benker.io.

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

A URL for opening Payment Page consists of a set of parameters, which are signed to secure the data transmitted to the Benker payment platform. SDK for Java allows you to seamlessly sign parameters and generate URLs. 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.CUSTOMER_ID, "customer_112") // Customer ID
      .setParam(Payment.PAYMENT_DESCRIPTION, "Test payment"); // Payment description (optional)

All parameters in this example, except for the payment description, are mandatory for any purchase.

You can also use any other optional parameters available for Payment Page. For more information about the Payment Page invocation parameters, see Parameters for opening the payment form.

Create a gate instance and initiate it with the secret key you obtained from the Benker technical support specialists. The secret key is required to sign parameters.
```
Gate gate = new Gate("<secret_key>");
   // Secret key you obtained from technical support service
```

Generate the URL for opening the payment form:

String paymentUrl = gate.getPurchasePaymentPageUrl(payment);

The URL must contain payment parameters and signature (abbreviated):

https://paymentpage.benker.io/payment?signature=OEKRlLXQsa2..
               ..gWg%3D%3D&payment_id=pid_1555943554067...

Use the generated URL for opening the payment form (details).

Here is an example of generating a URL for opening a payment form in English. The payment method selection page includes detailed payment information including amount, currency, and short payment description.

Figure 1. Example of generating the URL for opening Payment Page

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.CUSTOMER_ID, "customer_112") // Customer ID
	 .setParam(Payment.PAYMENT_DESCRIPTION, "Test payment");  // Payment description
	 .setParam(Payment.LANGUAGE_CODE, ("en");     // Language code to use in payment form
Gate gate = new Gate("<secret_key>");   // Secret key
String paymentUrl = gate.getPurchasePaymentPageUrl(payment);  // Complete request with signature

Using the test mode

When working with the SDK for Java, you can use the test mode. It allows you to check completeness and correctness of specified parameters and get information about errors if there were any.

Before using the test mode, make sure that the server of the web service can send the HTTP requests to sdk.benker.io. This allows you to specify various parameters to open the payment form as part of the testing activities (you will be able to use both test and production parameters) and to analyse error information. Use the following code:

Payment payment = new Payment(<project_id>, "<payment_id_in_your_service>");
payment.payment_amount = 1001;
payment.payment_currency = "EUR";
payment.payment_description = "Test payment";
 
Gate gate = new Gate('<secret_key>');
 
try {
    return gate.getPurchasePaymentPageUrl(payment);  
    // Receiving the URL to open the payment form
} catch (ValidationException e) { // Validating possible exceptions
    System.out.println(e); // Error message output
}
 
return null;

Information about the errors that occurred in testing is provided in error messages as follows:

One or more parameters is not valid:
 
Customer_id:
    Must be not null // The id of the customer, required for this request, was not specified
Account_token:
    Invalid account token  // Incorrect token value was specified

If there are no errors, then the generated URL for opening Payment Page is correct.

Processing callbacks

The Benker payment platform sends payment results to the callback URL you specified when connecting to Benker. 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 do it earlier.
```
Gate gate = new Gate("<secret_key>");
```
Create an instance of Callback by using the JSON string from the callback obtained from the Benker payment platform:
```
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.

Figure 2. Sample payment callback

POST /notify/success HTTP/1.1
Content-Length: 1237
User-Agent: GuzzleHttp/6.3.3 curl/7.47.0 PHP/7.0.32-0ubuntu0.16.04.1
Content-Type: application/json
Host: webservice.com

{
  "project_id": 200,
  "payment": {
    "id": "abc12345",
    "type": "purchase",
    "status": "success",
    "date": "2025-03-20T14:22:06+0000",
    "method": "Greek Banks",
    "sum": {
      "amount": 1000,
      "currency": "EUR"
    },
    "description": "Success"
  },
  "customer": {
    "id": "123"
  },
  "operation": {
    "id": 9529253065607,
    "type": "sale",
    "status": "success",
    "date": "2025-03-20T14:22:06+0000",
    "created_date": "2025-03-20T14:22:00+0000",
    "request_id": "f1de353331a01fd14163fe4226-00009530",
    "sum_initial": {
      "amount": 1000,
      "currency": "EUR"
    },
    "sum_converted": {
      "amount": 1000,
      "currency": "EUR"
    },
    "code": "0",
    "message": "Success",
    "provider": {
      "id": 1914,
      "payment_id": "",
      "auth_code": ""
    }
  },
  "signature": "OBjT3RaJnOWsDXOclvWoC6+CFSCtLprTo8VFbN6BYVQD2tVK/3d9k+RRA/7N9TV6OQqk+0uPUnx4/c8uaUurw=="
}