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.
Unzer unzer = new Unzer('s-priv-xxxxxxxxxx');
Card card = new Card("4711100000000000", "03/99");
card.setCvc("123");
card = unzer.createPaymentType(card);
Unzer unzer = new Unzer('s-priv-xxxxxxxxxx');
SepaDirectDebit sdd = new SepaDirectDebit("DE89370400440532013000");
sdd = unzer.createPaymentType(sdd);
Unzer unzer = new Unzer('s-priv-xxxxxxxxxx');
Paypal paypal = new Paypal();
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.
// update Unzer Installment payment type
Unzer unzer = new Unzer('s-priv-xxxxxxxxxx');
InstallmentSecuredRatePlan installmentSecuredRatePlan = unzer.fetchPaymentType("s-priv-1");
Instant now = Instant.now();
Instant yesterday = now.minus(1, ChronoUnit.DAYS);
installmentSecuredRatePlan.setIban("DE89370400440532013000");
installmentSecuredRatePlan.setBic("COBADEFFXXX");
installmentSecuredRatePlan.setAccountHolder("Peter Universum");
installmentSecuredRatePlan.setInvoiceDate(Date.from(yesterday));
installmentSecuredRatePlan.setInvoiceDueDate(Date.from(yesterday));
installmentSecuredRatePlan = unzer.updatePaymentType(installmentSecuredRatePlan);