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

You can fetch the payment resource using its ID or the order ID, which can be set when authorizing or charging.

$unzer     = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$card      = $unzer->fetchPaymentType('s-crd-9wmri5mdlqps');
$authorize = $card->authorize(100.0, 'EUR', 'https://your.return.url');

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

// ... to this one.
$payment = $unzer->fetchPayment($authorize->getPaymentId());
$unzer     = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$card      = $unzer->fetchPaymentType('s-crd-9wmri5mdlqps');
$authorize = $card->authorize(100.0, 'EUR', 'https://your.return.url', null, 'myOrderId');

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

// ... to this one.
$fetchedPayment = $unzer->fetchPaymentByOrderId('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.

The method Payment::cancelAmount(…) provides automatic cancellation for 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 workflow

payment-cancelAmount-Flow.png

Payment cancel examples

$unzer         = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$payment       = $unzer->fetchPayment('s-pay-2005');
$cancellations = $payment->cancelAmount();

// ... or (for Instalment secured)
$cancellations = $payment->cancelAmount(null, UnzerSDK\Constants\CancelReasonCodes::REASON_CODE_CANCEL);
$unzer         = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$payment       = $unzer->fetchPayment('s-pay-2005');
$cancellations = $payment->cancelAmount(123.45);

// ... or (for Instalment secured)
$cancellations = $payment->cancelAmount(123.45, UnzerSDK\Constants\CancelReasonCodes::REASON_CODE_CANCEL);
$unzer         = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$cancellations = $unzer->cancelPayment('s-pay-2005');

// ... or (for Instalment secured)
$cancellations = $unzer->cancelPayment('s-pay-2005', UnzerSDK\Constants\CancelReasonCodes::REASON_CODE_CANCEL);
$unzer         = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$cancellations = $unzer->cancelPayment('s-pay-2005', 123.45);

// ... or (for Instalment secured)
$cancellations = $unzer->cancelPayment('s-pay-2005', 123.45, UnzerSDK\Constants\CancelReasonCodes::REASON_CODE_CANCEL);

Arguments to Payment::cancelAmount

Name Type Description
amount float The amount to be cancelled.
When this parameter is left empty or set null the whole payment will be cancelled.
Required: false
Default: null
reasonCode UnzerSDK\Constants\CancelReasonCodes The reason for cancellation.
Required: In case of Invoice secured payment type.
Default: UnzerSDK\Constants\CancelReasonCodes::REASON_CODE_CANCEL
paymentReference string The reference string shown on the bank statement of the customer.
Required: false
Default: null
amountNet string The NET amount to be cancelled.
Required: Only for instalment payment type.
Default: null
amountVat string The VAT amount to be cancelled.
Required: Only for instalment payment type.
Default: null

Arguments to Unzer::cancelPayment

Name Type Description
payment string | UnzerSDK\Resources\Payment The ID of the payment resource or the Payment object itself.
Required: true
amount float The amount to be cancelled.
When this parameter is left empty or set null the whole payment will be cancelled.
Required: false
Default: null
reasonCode UnzerSDK\Constants\CancelReasonCodes The reason for cancellation.
Required: In case of Invoice secured payment type.
Default: UnzerSDK\Constants\CancelReasonCodes::REASON_CODE_CANCEL
referenceText string The reference string shown on the bank statement of the customer.
Required: false
Default: null
amountNet string The NET amount to be cancelled.
Required: Only for instalment payment type.
Default: null
amountVat string The VAT amount to be cancelled.
Required: Only for instalment payment type.
Default: null

Customer resource

Creating a 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 needed 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 create the corresponding resource either by calling Unzer->createCustomer($customer) or by using it in a transaction call e. g. Unzer::authorize(...) which will implicitly create the customer resource if required.
$unzer    = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$customer = UnzerSDK\Resources\CustomerFactory::createCustomer('Max', 'Mustermann');
$unzer->createCustomer($customer);
$unzer    = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$address  = (new UnzerSDK\Resources\EmbeddedResources\Address())
            ->setName('Max Mustermann')
            ->setStreet('Musterstraße. 2')
            ->setZip('12345')
            ->setCity('Musterstadt')
            ->setCountry('DE')
            ->setState('DE-1');

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

$unzer->createCustomer($customer);
$unzer    = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$address  = (new UnzerSDK\Resources\EmbeddedResources\Address())
            ->setName('Max Mustermann')
            ->setStreet('Musterstraße. 2')
            ->setZip('12345')
            ->setCity('Musterstadt')
            ->setCountry('DE')
            ->setState('DE-1');

$customer = UnzerSDK\Resources\CustomerFactory::createNotRegisteredB2bCustomer(
            'Max',
            'Mustermann',
            '2000-12-12',
            $address,
            'info@unzer.com',
            'abc GmbH',
            UnzerSDK\Constants\CompanyCommercialSectorItems::ACCOMMODATION
        );

$unzer->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 UnzerSDK\Resources\EmbeddedResources\Address The billing address.
Required: true
email string The email address of the customer.
Required: true
company string The company name.
Required: true
commercialSector UnzerSDK\Constants\CompanyCommercialSectorItems The commercial sector of the company.
Required: false
Default: UnzerSDK\Constants\CompanyCommercialSectorItems::OTHER

Arguments of the method CustomerFactory::createRegisteredB2bCustomer()

Name Type Description
billingAddress UnzerSDK\Resources\EmbeddedResources\Address The billing address of the customer.
Required: true
commercialRegisterNumber string The lastname of the customer.
Required: true
company string The company name.
Required: true
commercialSector UnzerSDK\Constants\CompanyCommercialSectorItems The commercial sector of the company.
Required: false
Default: UnzerSDK\Constants\CompanyCommercialSectorItems::OTHER

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 and then referenced by the payment.
$unzer         = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$ppl           = $unzer->fetchPaymentType('s-ppl-9wmri5mdlqps');
$authorization = $ppl->authorize(100.0, 'EUR', 'https://your.return.url', $customerId);
$unzer = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$ppl   = new UnzerSDK\Resources\PaymentTypes\Paypal()
$ppl   = $unzer->createPaymentType($ppl);

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

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

$customer = UnzerSDK\Resources\CustomerFactory::createCustomer('Max', 'Mustermann')
            ->setSalutation(UnzerSDK\Constants\Salutations::MR)
            ->setBirthDate('1989-12-24')
            ->setEmail('info@unzer.com')
            ->setBillingAddress($address)
            ->setShippingAddress($shippingAddress);

$authorization = $ppl->authorize(100.0, 'EUR', 'https://your.return.url', $customer);
$unzer  = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$ddg    = $unzer->fetchPaymentType('s-ddg-b1uymcomj20c');
$charge = $ddg->charge(100.0, 'EUR', 'https://your.return.url', $customerId);
$unzer = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$ddg   = new UnzerSDK\Resources\PaymentTypes\SepaDirectDebitGuaranteed('DE89370400440532013000');
$ddg   = $unzer->createPaymentType($ddg);

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

$customer = UnzerSDK\Resources\CustomerFactory::createCustomer('Max', 'Mustermann')
            ->setSalutation(UnzerSDK\Constants\Salutations::MR)
            ->setBirthDate('1989-12-24')
            ->setEmail('info@unzer.com')
            ->setBillingAddress($address)
            ->setShippingAddress($address);

$charge = $ddg->charge(100.0, 'EUR', 'https://your.return.url', $customer);

Fetching a customer resource

The Unzer class provides a method to fetch a Customer object by its resource ID which has been set by the API on creation. However, because your shop has its own ID for its customers, you can also fetch it from the PAPI using the external ID, that you set while creating it.

$unzer    = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$customer = UnzerSDK\Resources\CustomerFactory::createCustomer('Max', 'Mustermann');

// This customer object is equal…
$unzer->createCustomer($customer);

// …to this one.
$fetchedCustomer = $unzer->fetchCustomerByExtCustomerId('MyCustomerId');
$unzer    = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$customer = UnzerSDK\Resources\CustomerFactory::createCustomer('Max', 'Mustermann');

// This customer object is equal…
$unzer->createCustomer($customer);

// …to this one.
$fetchedCustomer = $unzer->fetchCustomer($customer->getId());
Please keep in mind that the value for customerId has to be unique for the used key pair.

Metadata resource

You can also add custom data to a payment resource by creating a UnzerSDK\Resources\Metadata object, and add it to the charge or the authorization call.

$unzer    = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$metadata = new UnzerSDK\Resources\Metadata();
$metadata->addMetadata('MyCustomData', 'my custom value');

$card   = $unzer->fetchPaymentType('s-crd-9wmri5mdlqps');
$charge = $card->charge(1.23, 'EUR', 'https://your.return.url', null, null, $metadata);
$unzer    = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$metadata = new UnzerSDK\Resources\Metadata();
$metadata->addMetadata('MyCustomData', 'my custom value');

$card      = $unzer->fetchPaymentType('s-crd-9wmri5mdlqps');
$authorize = $card->authorize(1.23, 'EUR', 'https://your.return.url', null, null, $metadata);

Basket resource

For some payment types it is necessary to send in detailed information on the purchased goods (e. g. to determine risk for secured payment types). Please refer to the Basket section for information on the Basket resource.

The following examples show how to handle the basket resource.

$unzer      = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$basketItem = (new UnzerSDK\Resources\EmbeddedResources\BasketItem())
                  ->setBasketItemReferenceId('Artikelnummer4711')
                  ->setQuantity(5)
                  ->setAmountPerUnit(100.1)
                  ->setAmountNet(420.1)
                  ->setTitle('Apple iPhone')
                  ->setSubTitle('Red case')
                  ->setImageUrl('https://url.to.the.basket.item.image')
                  ->setType(UnzerSDK\Constants\BasketItemTypes::GOODS);

$basket  = (new UnzerSDK\Resources\Basket())
                  ->setAmountTotalGross(500.5)
                  ->setCurrencyCode('EUR')
                  ->setOrderId('uniqueOrderId_1')
                  ->addBasketItem($basketItem);

$unzer->createBasket($basket);
$unzer  = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$basket = $unzer->fetchBasket('s-bsk-1');
$unzer      = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$basketItem = (new UnzerSDK\Resources\EmbeddedResources\BasketItem())
                  ->setBasketItemReferenceId('Artikelnummer4711')
                  ->setQuantity(5)
                  ->setAmountPerUnit(100.1)
                  ->setAmountNet(420.1)
                  ->setTitle('Apple iPhone')
                  ->setSubTitle('Red case')
                  ->setImageUrl('https://url.to.the.basket.item.image')
                  ->setType(UnzerSDK\Constants\BasketItemTypes::GOODS);
$basket  = (new UnzerSDK\Resources\Basket())
                  ->setAmountTotalGross(500.5)
                  ->setCurrencyCode('EUR')
                  ->setOrderId('uniqueOrderId_1')
                  ->addBasketItem($basketItem);

$unzer->createBasket($basket);

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

$customer = (new UnzerSDK\Resources\Customer())
            ->setFirstname('Max')
            ->setLastname('Mustermann')
            ->setSalutation(UnzerSDK\Constants\Salutation::MR)
            ->setBirthDate('1989-12-24')
            ->setEmail('info@unzer.com')
            ->setBillingAddress($address);

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

$charge = $ddg->charge(100.0, 'EUR', 'https://your.return.url', $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.

Refer to the basic information on the Keypair-resource here Keypair.

$unzer   = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$keypair = $unzer->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.

$unzer   = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$keypair = $unzer->fetchKeypair(true);