Basic usage of the SDK

The Unzer 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 the client you can provide the locale within the second argument. Please refer to this chapter for a list of supported locales.

// create the heidelpay object
$heidelpay = new heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');
// create the heidelpay object with language
$heidelpay = new heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx', 'de-DE');

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.

$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$card = new \heidelpayPHP\Resources\PaymentTypes\Card('4444333322221111', '03/20');
$card->setCvc('123');
$card = $heidelpay->createPaymentType($card);
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$paypal = new \heidelpayPHP\Resources\PaymentTypes\Paypal();
$paypal = $heidelpay->createPaymentType($paypal);
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$invoice = new \heidelpayPHP\Resources\PaymentTypes\Invoice();
$invoice = $heidelpay->createPaymentType($invoice);
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$prepayment = new \heidelpayPHP\Resources\PaymentTypes\Prepayment();
$prepayment = $heidelpay->createPaymentType($prepayment);
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$p24 = new \heidelpayPHP\Resources\PaymentTypes\Przelewy24();
$p24 = $heidelpay->createPaymentType($p24);
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$giropay = new \heidelpayPHP\Resources\PaymentTypes\Giropay();
$giropay = $heidelpay->createPaymentType($giropay);
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$directDebitGuaranteed = new \heidelpayPHP\Resources\PaymentTypes\SepaDirectDebitGuaranteed('DE89370400440532013000');
$directDebitGuaranteed = $heidelpay->createPaymentType($directDebitGuaranteed);
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$directDebit = new \heidelpayPHP\Resources\PaymentTypes\SepaDirectDebit('DE89370400440532013000');
$directDebit = $heidelpay->createPaymentType($directDebit);
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$ivf = new \heidelpayPHP\Resources\PaymentTypes\InvoiceFactoring();
$ivf = $heidelpay->createPaymentType($ivf);
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$ideal = (new \heidelpayPHP\Resources\PaymentTypes\Ideal())->setBic('RABONL2U');
$ideal = $heidelpay->createPaymentType($ideal);
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$sofort = new \heidelpayPHP\Resources\PaymentTypes\Sofort();
$sofort = $heidelpay->createPaymentType($sofort);
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$eps = new \heidelpayPHP\Resources\PaymentTypes\EPS();
$eps = $heidelpay->createPaymentType($eps);
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$pis = new \heidelpayPHP\Resources\PaymentTypes\PIS();
$pis = $heidelpay->createPaymentType($pis);
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$alipay = new \heidelpayPHP\Resources\PaymentTypes\Alipay();
$alipay = $heidelpay->createPaymentType($alipay);
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$wechatpay = new \heidelpayPHP\Resources\PaymentTypes\Wechatpay();
$wechatpay = $heidelpay->createPaymentType($wechatpay);
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

// get available instalment plans
$today = new \DateTime('now');
$instalmentPlans = $heidelpay->fetchDirectDebitInstalmentPlans(119.0, 'EUR', 4.99, $today);

// select instalment plan
$selectedPlan = $instalmentPlans->getPlans()[0];

$hdd = new \heidelpayPHP\Resources\PaymentTypes\HirePurchaseDirectDebit($selectedPlan, 'DE46940594210000012345', 'Manuel WeiƟmann', $today, 'COBADEFFXXX', $today, $today);
$hdd = $heidelpay->createPaymentType($hdd);
Restrictions on card types
You cannot create credit card types with the PHP SDK unless you are fully PCI DSS certified.
Please refer to our Web Integration to learn how to use our UIComponents to handle card information.

Update a Payment Type resource

Properties of Unzer Instalment payment types can be updated.

// update Unzer Instalment payment type
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

/** @var \heidelpayPHP\Resources\PaymentTypes\HirePurchaseDirectDebit $hdd */
$hdd = $heidelpay->fetchPaymentType('s-priv-1');

$yesterday = (new \DateTime())->add(\DateInterval::createFromDateString('yesterday');

$hdd->setIban('DE89370400440532013000')
            ->setBic('COBADEFFXXX')
            ->setAccountHolder('Peter Universum')
            ->setInvoiceDate($yesterday)
            ->setInvoiceDueDate($yesterday);

$hdd = $heidelpay->updatePaymentType($hdd);