Basic usage of the SDK

The heidelpay object

The heidelpay object is the main object. You always need it, in order to communicate with the UnzerAPI. In addition it is the facade to all functionality in the SDK.

  • It provides the methods to perform CRUD operations on the resources (payment type, customer, basket, etc.)
  • It provides methods that allow transactions like authorization, charge, cancellation (i.e.refund and reversal) and shipment

This means you will have to create the heidelpay object and provide your private-key prior to everything you want to do with the SDK.

In order to show potential error messages in the language of your system, you can create HttpClientBasedRestCommunication object with Locale, then pass this object as heidelpay constructor argument. Please refer to this chapter for a list of supported locales.

// create the heidelpay object

Heidelpay heidelpay = new Heidelpay("s-priv-xxxxxxxxxx");
// create the heidelpay object with language

Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(Locale.GERMANY), key);

The Payment object

Whenever an authorization or a charge transaction is performed on a payment type a payment instance is automatically created.

The object contains all information on the payment process and ties all required resources together. These are some of the information the payment object stores:

  • references to customer, payment type, etc.
  • references to transactions: charges, authorization, shipment
  • the amount information: total, charged, canceled and remaining
  • the currency
  • the state of the payment: pending, canceled, completed, etc.

By fetching the payment object, one can access all information on the whole payment process.

Creating a Payment Type resource

In order to perform transactions the API needs to know, which payment type to use. There are two options here:

  1. reference a payment type that already exists (e. g. registered credit card)
  2. create and reference a new payment type

The following examples show how to create the different payment types.

Card card = new Card("4444333322221111", "03/20");
card.setCvc("123");
Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");
card = heidelpay.createPaymentType(card);
Paypal paypal = new Paypal();
Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");
paypal = heidelpay.createPaymentType(paypal);
Invoice invoice = new Invoice();
Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");
invoice = heidelpay.createPaymentType(invoice);
Prepayment prepayment = new Prepayment();
Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");
prepayment = heidelpay.createPaymentType(prepayment);
Przelewy24 p24 = new Przelewy24();
Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");
p24 = getHeidelpay().createPaymentType(p24);
Giropay giropay = new Giropay();
Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");
giropay = heidelpay.createPaymentType(giropay);
SepaDirectDebitGuaranteed sdd = new SepaDirectDebitGuaranteed("DE89370400440532013000"); //iban
sdd.setBic("VALID_BIC");
sdd.setHolder("VALID_HOLDER");
Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");
sdd = heidelpay.createPaymentType(sdd);
Wechatpay wechatpay = new Wechatpay();
Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-2a107CYZMp3UbyVPAuqWoxQHi9nFyeiW");
wechatpay = heidelpay.createPaymentType(wechatpay);
InvoiceFactoring invoice = new InvoiceFactoring();
Heidelpay heidelpay = new heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");
invoice = heidelpay.createPaymentType(invoice);
SepaDirectDebit sdd = new SepaDirectDebit("DE89370400440532013000");
sdd.setBic("VALID_BIC");
sdd.setHolder("VALID_HOLDER");
Heidelpay heidelpay = new heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");
sdd = heidelpay.createPaymentType(sdd);
Heidelpay heidelpay = new heidelpay("s-priv-xxxxxxxxxx");
Customer customer = heidelpay.createCustomer(getMaximumCustomer(getRandomId()));
String typeId = createPaymentTypeCard().getId();
Recurring recurring = heidelpay.recurring(typeId
             , customer.getId()
             , new URL("https://www.unzer.com"));

assertRecurring(recurring, Recurring.Status.PENDING);
assertNotNull(recurring.getRedirectUrl());

Card type = (Card)heidelpay.fetchPaymentType(typeId);
assertEquals(false, type.getRecurring());
InvoiceGuaranteed invoice = new InvoiceGuaranteed();
Heidelpay heidelpay = new heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");
invoice = heidelpay.createPaymentType(invoice);
Ideal ideal = new Ideal().setBic("RABONL2U");
ideal.setBic("VALID_BIC");
Heidelpay heidelpay = new heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");
ideal = heidelpay.createPaymentType(ideal);
Sofort sofort = new Sofort();
Heidelpay heidelpay = new heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");
sofort = heidelpay.createPaymentType(sofort);
Eps eps = new Eps();
eps.setBic("VALID_BIC");
Heidelpay heidelpay = new heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");
eps = heidelpay.createPaymentType(eps);
Pis pis = new Pis();
pis.setIban("VALID_IBAN");
pis.setBic("VALID_BIC");
pis.setHolder("VALID_HOLDER");
Heidelpay heidelpay = new heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");
pis = heidelpay.createPaymentType(pis);
Alipay alipay = new Alipay();
Heidelpay heidelpay = new heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");
alipay = heidelpay.createPaymentType(alipay);
PostFinanceCard pfCard = new PostFinanceCard();
Heidelpay heidelpay = new heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");
pfCard = heidelpay.createPaymentType(pfCard);
PostFinanceEFinance pfEFinance = new PostFinanceEFinance();
Heidelpay heidelpay = new heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");
pfEFinance = heidelpay.createPaymentType(pfEFinance);
Restrictions on card types
You cannot create credit card types with the JAVA SDK unless you are fully PCI DSS certified.