Additional Resources

Payment resource

The payment resource can not be created on its own but will automatically appear when an authorization or direct charge takes place.

Fetching a Payment

The payment resource can be fetched using its id or the external order id which has been set while performing the transaction.

// Fetching a payment by id

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

$card = $heidelpay->fetchPaymentType('s-crd-9wmri5mdlqps');

$authorize = $card->authorize(100.0, 'EUR', 'https://www.heidelpay.com');

// This payment object is equal ...
$payment = $authorize->getPayment();

// ... to this one.
$payment = $heidelpay->fetchPayment($authorize->getPaymentId());
// Fetch a payment by external orderId

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

$card = $heidelpay->fetchPaymentType('s-crd-9wmri5mdlqps');

$authorize = $card->authorize(100.0, 'EUR', 'https://www.heidelpay.com', null, 'myOrderId');

// This payment object is equal ...
$payment = $authorize->getPayment();

// ... to this one.
$fetchedPayment = $heidelpay->fetchPayment('myOrderId');
Info/tip
Please keep in mind that the value for orderId has to be unique for the used KeyPair.

Cancelling a Payment

When cancelling a payment several different scenarios have to be taken into account. In version 1.2.3.0 of the SDK the method Payment::cancelAmount()has been added which covers the following cases of cancellation:

  • Full cancel of a single Charge
  • Full cancel on an Authorization with several Charges
  • Part cancel on a single Charge
  • Part cancel on several Charges
  • Full cancel on an Authorization without Charges
  • Full cancel on Authorization without Charges after part cancel
  • Full cancel on full charged Authorization
  • Full cancel on partly charged Authorization
  • Part cancel on an Authorization with Charges
  • Full cancel on payment type with initializing charge (e.g. Invoice)
  • Part cancel on payment type with initializing charge (e.g. Invoice)
Cancel work flow

payment-cancelAmount-Flow.png

Payment cancel examples
// Full cancel on payment

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

$payment = $this->heidelpay->fetchPayment('s-pay-2005');
$cancellations = $payment->cancelAmount();

// ... or
$cancellations = $payment->cancelAmount(null, \heidelpayPHP\Constants\CancelReasonCodes::REASON_CODE_CANCEL);
// Part cancel on Payment

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

$payment = $this->heidelpay->fetchPayment('s-pay-2005');
$cancellations = $payment->cancelAmount(123.45);

// ... or
$cancellations = $payment->cancelAmount(123.45, \heidelpayPHP\Constants\CancelReasonCodes::REASON_CODE_CANCEL);
Payment::cancelAmount Params
Name Type Description
$totalCancelAmount float The amount to be cancelled.
When this parameter is left out or set null the whole payment will be cancelled.
Required: false
Default: null
$reason string (\heidelpayPHP\Constants\CancelReasonCodes) The reason for cancellation (required in case of the Unzer Invoice Secured payment type).
Required: false
Default: \heidelpayPHP\Constants\CancelReasonCodes::REASON_CODE_CANCEL

Customer resource

Create customer resources

There are three different customer types:

  • B2C Customer
  • registered B2B Customer
  • not-registered B2B Customer

They only differ in the mandatory parameters but use the same Customer-class and resource.

We added the CustomerFactory to provide for an easy way to create the desired Customer object. It contains three static methods with the required arguments and returns the customer object to be created.

The Customer object created with the CustomerFactory is not yet known to the API.
You can corresponding resource either by calling heidelpay::createCustomer($customer) or by using it in a transaction call e. g. heidelpay::authorize(...) which will implicitly create the customer resource if required.
// create a B2C customer

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

$customer = \heidelpayPHP\Resources\CustomerFactory::createCustomer('Max', 'Mustermann');

$heidelpay->createCustomer($customer);
// create a registered B22 customer

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

$address  = (new \heidelpayPHP\Resources\EmbeddedResources\Address())
            ->setName('Max Mustermann')
            ->setStreet('Musterstraße. 2')
            ->setZip('12345')
            ->setCity('Musterstadt')
            ->setCountry('DE')
            ->setState('DE-1');

$customer = CustomerFactory::createRegisteredB2bCustomer(
            $address,
            '123',
            'abc GmbH',
            \heidelpayPHP\Constants\CompanyCommercialSectorItems::ACCOMMODATION
        );

$heidelpay->createCustomer($customer);
// create a non-registered B2B customer

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

$address  = (new \heidelpayPHP\Resources\EmbeddedResources\Address())
            ->setName('Max Mustermann')
            ->setStreet('Musterstraße. 2')
            ->setZip('12345')
            ->setCity('Musterstadt')
            ->setCountry('DE')
            ->setState('DE-1');

$customer = CustomerFactory::createNotRegisteredB2bCustomer(
            'Max',
            'Mustermann',
            '2000-12-12',
            $address,
            'test@heidelpay.com',
            'abc GmbH',
            \heidelpayPHP\Constants\CompanyCommercialSectorItems::ACCOMMODATION
        );

$heidelpay->createCustomer($customer);

Arguments of the method CustomerFactory::createCustomer()

Name Type Description
$firstname string The firstname of the customer.
Required: true
$lastname string The lastname of the customer.
Required: true

Arguments of the method CustomerFactory::createNotRegisteredB2bCustomer()

Name Type Description
$firstname string The firstname of the customer.
Required: true
$lastname string The lastname of the customer.
Required: true
$birthDate string The birthdate of the customer.
Required: true
Format: ‘YYYY-MM-DD’
$billingAddress \heidelpayPHP\Resources\EmbeddedResources\Address The billing address of the customer.
Required: true
$email string The email address of the customer.
Required: true
$company string The company name of the customer.
Required: true
$commercialSector string (\heidelpayPHP\Constants\CompanyCommercialSectorItems) The commercial sector of the customer.
Required: false
Default: ‘OTHER’

Arguments of the method CustomerFactory::createRegisteredB2bCustomer()

Name Type Description
$billingAddress \heidelpayPHP\Resources\EmbeddedResources\Address The billing address of the customer.
Required: true
$commercialRegisterNumber string The lastname of the customer.
Required: true
$company string The birthdate of the customer.
Required: true
Format: ‘YYYY-MM-DD’
commercialSector string (\heidelpayPHP\Constants\CompanyCommercialSectorItems) The billing address of the customer.
Required: true

Using the customer resource

Some payment types require a Customer resource within the initial transaction (Charge or Authorize), which can be passed as additional parameter to the transaction call as shown in the following examples.

The Customer reference...
…can be passed as customerId or as a customer object.
If the customer object has not been created yet (i. e. does not have an id) it will be automatically be created with the API and then referenced by the payment.
// authorize example with customer id

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

$ppl = $heidelpay->fetchPaymentType('s-ppl-9wmri5mdlqps');

$authorization = $ppl->authorize(100.0, 'EUR', 'https://www.heidelpay.com', $customerId);
// authorize example with B2C  customer object

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

$ppl = new \heidelpayPHP\Resources\PaymentTypes\Paypal()
$ppl = $heidelpay->createPaymentType($ppl);

$address  = (new \heidelpayPHP\Resources\EmbeddedResources\Address())
            ->setName('Max Mustermann')
            ->setStreet('Musterstraße. 2')
            ->setZip('12345')
            ->setCity('Musterstadt')
            ->setCountry('DE')
            ->setState('DE-1');

$shippingAddress  = (new \heidelpayPHP\Resources\EmbeddedResources\Address())
            ->setName('Moriz Mustermann')
            ->setStreet('Musterstraße. 12')
            ->setZip('12345')
            ->setCity('Musterstadt')
            ->setCountry('DE')
            ->setState('DE-1');

$customer = \heidelpayPHP\Resources\CustomerFactory::createCustomer('Max', 'Mustermann')
            ->setSalutation(Salutations::MR)
            ->setBirthDate('1989-12-24')
            ->setEmail('max.mustermann@musterfirma.de')
            ->setBillingAddress($address)
            ->setShippingAddress($shippingAddress);

$authorization = $ppl->authorize(100.0, 'EUR', 'https://www.heidelpay.com', $customer);
// charge example with customer id

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

$ddg = $heidelpay->fetchPaymentType('s-ddg-b1uymcomj20c');

$charge = $ddg->charge(100.0, 'EUR', 'https://www.heidelpay.com', $customerId);
// charge example with B2C customer object

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

$ddg = new \heidelpayPHP\Resources\PaymentTypes\SepaDirectDebitGuaranteed('DE89370400440532013000');
$ddg = $heidelpay->createPaymentType($ddg);

$address  = (new \heidelpayPHP\Resources\EmbeddedResources\Address())
            ->setName('Max Mustermann')
            ->setStreet('Musterstraße. 2')
            ->setZip('12345')
            ->setCity('Musterstadt')
            ->setCountry('DE')
            ->setState('DE-1');

$customer = \heidelpayPHP\Resources\CustomerFactory::createCustomer('Max', 'Mustermann')
            ->setSalutation(\heidelpayPHP\Constants\Salutations::MR)
            ->setBirthDate('1989-12-24')
            ->setEmail('max.mustermann@musterfirma.de')
            ->setBillingAddress($address)
                        ->setShippingAddress($address);

$charge = $ddg->charge(100.0, 'EUR', 'https://www.heidelpay.com', $customer);

Fetching a customer resource

The Unzer facade provides for a method to fetch a customer by the resources id which has been set by the API on creation. However since your shop has its own id for its customers we added the possibility to fetch it using the external id set while creating it.

// Fetch a customer by id

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

$customer = \heidelpayPHP\Resources\CustomerFactory::createCustomer('Max', 'Mustermann')
            ->setSalutation(Salutations::MR)
            ->setBirthDate('1989-12-24')
            ->setEmail('max.mustermann@musterfirma.de')
                        ->setCustomerId('MyCustomerId');

// This customer object is equal ...
$heidelpay->createCustomer($customer);

// ... to this one.
$fetchedCustomer = $heidelpay->fetchCustomerByExtCustomerId('MyCustomerId');
// Fetch a customer by external customerid

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

$customer = \heidelpayPHP\Resources\CustomerFactory::createCustomer('Max', 'Mustermann')
            ->setSalutation(Salutations::MR)
            ->setBirthDate('1989-12-24')
            ->setEmail('max.mustermann@musterfirma.de');

$heidelpay->createCustomer($customer);

$fetchedCustomer = $heidelpay->fetchCustomerByExtCustomerId($customer->getId());
Please keep in mind that the value for customerId has to be unique for the used KeyPair.

Metadata resource

The system allows you to add any custom data to a payment which can be used to pin additional information to it.

For this you need to create a metadata object and add it to the charge or authorization call:

// Add Metadata to a Charge

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

$metadata = new \heidelpayPHP\Resources\Metadata();
$metadata->addMetadata('MyCustomData', 'my custom value');

$card = $heidelpay->fetchPaymentType$heidelpay->fetchPaymentType('s-crd-9wmri5mdlqps');

$charge = $card->charge(1.23, 'EUR', 'https://heidelpay.com', null, null, $metadata);
// Add Metadata to a Authorize

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

$metadata = new \heidelpayPHP\Resources\Metadata();
$metadata->addMetadata('MyCustomData', 'my custom value');

$card = $heidelpay->fetchPaymentType$heidelpay->fetchPaymentType('s-crd-9wmri5mdlqps');

$authorize = $card->authorize(1.23, 'EUR', 'https://heidelpay.com', null, null, $metadata);
In previous versions metadata have been automatically created and sent with transactions such as authorize and charge. This has been changed in version 1.2.0.0. From this version on the SDK information is sent to the API in each request via HTTP-header.

The metadata is now only sent when it has been set explicitly.

Basket resource

For some payment types it is necessary to send in detailed information on the basket. Please refer to the Basket section for information on the Basket resource.

The following examples show how to handle the basket resource.

// Create Basket resource
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$basketItem = (new \heidelpayPHP\Resources\EmbeddedResources\BasketItem())
                            ->setBasketItemReferenceId('Artikelnummer4711')
                            ->setQuantity(5)
                            ->setAmountPerUnit(100.1)
                            ->setAmountNet(420.1)
                            ->setTitle('Apple iPhone')
                            ->setSubTitle('Red case')
              ->setImageUrl('https://files.readme.io/9f556bd-small-Heidelpay-Logo_mitUnterzeile-orange_RGB.jpg')
                ->setType(\heidelpayPHP\Constants\BasketItemTypes::GOODS);
$basket  = (new \heidelpayPHP\Resources\Basket())
                            ->setAmountTotalGross(500.5)
                            ->setCurrencyCode('EUR')
                            ->setOrderId('uniqueOrderId_1')
                            ->addBasketItem($basketItem);

$this->heidelpay->createBasket($basket);
// Fetch Basket resource

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

$basket  = $heidelpay->fetchBasket('s-bsk-1');
// Full example

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

$basketItem = (new \heidelpayPHP\Resources\EmbeddedResources\BasketItem())
                            ->setBasketItemReferenceId('Artikelnummer4711')
                            ->setQuantity(5)
                            ->setAmountPerUnit(100.1)
                            ->setAmountNet(420.1)
                            ->setTitle('Apple iPhone')
                            ->setSubTitle('Red case')
              ->setImageUrl('https://files.readme.io/9f556bd-small-Heidelpay-Logo_mitUnterzeile-orange_RGB.jpg')
                ->setType(\heidelpayPHP\Constants\BasketItemTypes::GOODS);
$basket  = (new \heidelpayPHP\Resources\Basket())
                            ->setAmountTotalGross(500.5)
                            ->setCurrencyCode('EUR')
                            ->setOrderId('uniqueOrderId_1')
                            ->addBasketItem($basketItem);

$this->heidelpay->createBasket($basket);

$address  = (new \heidelpayPHP\Resources\EmbeddedResources\Address())
            ->setName('Max Mustermann')
            ->setStreet('Musterstraße. 2')
            ->setZip('12345')
            ->setCity('Musterstadt')
            ->setCountry('DE')
            ->setState('DE-1');

$customer = (new \heidelpayPHP\Resources\Customer())
            ->setFirstname('Max')
            ->setLastname('Mustermann')
            ->setSalutation(Salutation::MR)
            ->setBirthDate('1989-12-24')
            ->setEmail('max.mustermann@musterfirma.de')
            ->setBillingAddress($address);

$ddg = $heidelpay->fetchPaymentType('s-ddg-23ashaor54');

$charge = $ddg->charge(100.0, 'EUR', 'https://www.heidelpay.com', $customer, null, null, $basket);

Keypair Resource

The Keypair-Resource allows for fetching information about the configuration of the merchant. The response will show the public key to the private key used as well as the security level (ref. PCI) and the available payment types.

Please refer to the basic information on the Keypair-resource here Keypair.

// Fetch information on the configuration of the merchant

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

$keypair = $heidelpay->fetchKeypair();

To obtain more detailed information on the merchants configuration you can set the detailed flag in the method call. This will add detailed information to the available payment types such as allowed currencies, supported (card) brands, etc.

// Fetch detailed information ont the configuration of the merchant

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

$keypair = $heidelpay->fetchKeypair(true);