Basic usage of the Java SDK
Learn about the basic usage of the Java SDK.
The Unzer object
The Unzer object is the main object. You always need it, in order to communicate with the Unzer API (PAPI). In addition it is the facade to all functionality in the SDK.
It provides:
- methods to perform CRUD operations on the resources (such as payment type, customer, and basket).
- methods that allow transactions such as authorization, and charge, cancellation (like refund and reversal), and shipment.
This means that you have to create the Unzer object and provide your private key before you can start using the SDK.
To display potential error messages in the language of the client, you can provide the locale within the second argument of the Unzer class constructor.
For a complete list of supported locales, see Localization.
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx", Locale.GERMANY);
Set ClientIp request header
For some server-side requests, the client’s IP must be manually added.
You can pass the clientIP when creating an instance of the Unzer object. This uses the clientIp in the header of all the request sent by this instance.
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx", Locale.GERMANY, null, "255.255.255.255");
The Payment object
Whenever an authorization or a charge transaction is performed successfully, an instance of the Payment class is automatically created.
The Payment object contains all the information on the payment process and ties all required resources together. The information includes:
- references to customer and payment type
- references to transactions: charges, authorization, shipment
- the amount information: total, charged, canceled and remaining
- the currency
- the state of the payment: pending, canceled, and completed
By fetching the Payment object, you can access all the information for the complete payment process.
For a full description of the payment resource, see Check payment details
Creating a payment type resource
To perform transactions, you must sent the payment type to the API. There are two options here:
- reference a payment type that already exists (for example, registered credit card)
- create and reference a new payment type
The following examples show how to create selected payment types.
// 1. Creating Unzer instance
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
// 2. Creating card information
Card card = new Card("4711100000000000", "03/99");
card.setCvc("123");
// 3. Creating payment type
card = unzer.createPaymentType(card);
// 1. Creating Unzer instance
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
// 2. Creating SEPA Direct Debit with IBAN
SepaDirectDebit sdd = new SepaDirectDebit("DE89370400440532013000");
// 3. Creating payment type
sdd = unzer.createPaymentType(sdd);
// 1. Creating Unzer instance
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
// 2. Creating PayPal instance
Paypal paypal = new Paypal();
// 3. Creating payment type
paypal = unzer.createPaymentType(paypal);
You cannot create the Card type with the Java SDK unless you are PCI compliant.
To learn how to use our UI Components to handle card information, see Card UI Components integration guide.
Update a Payment Type resource
Properties of the Unzer Installment payment type can be updated.
// 1. Creating Unzer instance
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
// 2. Fetch existing payment type by id
InstallmentSecuredRatePlan installmentSecuredRatePlan = unzer.fetchPaymentType("s-priv-1");
// 3. Creating date instances
Instant now = Instant.now();
Instant yesterday = now.minus(1, ChronoUnit.DAYS);
// 4. Setting payment details
installmentSecuredRatePlan.setIban("DE89370400440532013000");
installmentSecuredRatePlan.setBic("COBADEFFXXX");
installmentSecuredRatePlan.setAccountHolder("Peter Universum");
installmentSecuredRatePlan.setInvoiceDate(Date.from(yesterday));
installmentSecuredRatePlan.setInvoiceDueDate(Date.from(yesterday));
// 5. Update payment type with new details
installmentSecuredRatePlan = unzer.updatePaymentType(installmentSecuredRatePlan);