Performing Transactions

Authorize and (direct) Charge

An authorization transaction leads to the creation of an authorization resource and a payment resource. Similarly a charge transaction leads to the creation of a charge resource and a payment resource. To learn more about the payment methods that support authorization and charge, go to Authorize and the Charges.

Examples

In general, the transaction calls on a payment type require at least the amount, the currency and the returnUrl. See the following examples on both transaction types.

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

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

$customer = (new UnzerSDK\Resources\Customer())->setFirstname('Max')->setLastname('Mustermann');

$orderId = 'uniqueOrderId';

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

$basketItem = (new UnzerSDK\Resources\EmbeddedResources\BasketItem())
  ->setBasketItemReferenceId('Artikelnummer4711')
  ->setQuantity(5)
  ->setAmountPerUnit(100.1)
  ->setAmountNet(420.1)
  ->setTitle('Apple iPhone');
$basket  = (new UnzerSDK\Resources\Basket())
  ->setAmountTotalGross(500.5)
  ->setCurrencyCode('EUR')
  ->setOrderId($orderId)
  ->addBasketItem($basketItem);

$card3ds = true;

$authorize = $card->authorize(500.5, 'EUR', 'https://your.return.url', $customer, $orderId, $metadata, $basket, $card3ds, 'invoiceId', 'payment reference text');
// basic charge example
$unzer  = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$card   = $unzer->fetchPaymentType('s-crd-9wmri5mdlqps');
$charge = $card->charge(100.0, 'EUR', 'https://your.return.url');

Some payment types require a customer resource, which can be passed as additional parameter to the transaction.
Please refer to the Additional Resources section to learn more about adding a customer reference.

Arguments to direct charge and authorize transaction methods

Parameter Type Description
amount float The amount to be charged/authorized.
Required: true
currency string The currency of the amount.
Required: true
returnUrl string The URL the API leads the customer to, after he finished entering payment information outside of the shop (e.g. PayPal).
This needs to be set to a valid URL, no matter whether a redirect is necessary or not.
Required: true
customer UnzerSDK\Resources\Customer A reference to the customer resource corresponding to this payment.
This can be either a customer object or the ID of an existing customer resource. If a customer object is used whose ID is not set (i. e. the resource does not exist yet in the PAPI) the customer resource will automatically be created and referenced with the transaction call.
Find additional information here.
Required: false
Default: null
orderId string The ID of the order in your store.
This ID can be used to fetch the payment resource from the PAPI using the method Unzer::fetchPaymentByOrderId($YourOrderId)
Required: false
Default: null
metadata UnzerSDK\Resources\Metadata A reference to the metadata corresponding to this payment.
The metadata object can be used to pass along custom information which you whish to reference to the payment.
Find additional information here.
Required: false
Default: null
basket UnzerSDK\Resources\Basket A reference to the basket corresponding to this payment.
Find additional information here
Required: false
Default: null
card3ds boolean Allows to switch between a 3DS and non-3DS channel, if both are configured for the merchant. Otherwise it will be ignored.
Required: false
Default: null
invoiceId string This is used to transmit the invoiceId from your shop to the API.
Required: false
The invoiceId is necessary in case of Invoice payment, however it can also be transmitted later with the shipment call.
Default: null
paymentReference string This is a reference string to show the customer the purpose of the transaction. This will be shown on the bank statement of the buyer.
Required: false
Default: null
returnUrl
The argument returnUrl needs to be set to a valid URL, no matter whether a redirect is necessary for the payment type or not.

Charge an Authorization

If an authorization transaction has been performed the authorized amount can be charged. It is possible to perform several charges until the authorized amount is reached.

// charge authorized amount by payment ID
$unzer  = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$charge = $unzer->chargeAuthorization('s-pay-1');
// charge authorized amount by authorization object
$unzer         = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$authorization = $unzer->fetchAuthorization('s-pay-1');
$charge        = $authorization->charge();
// charge authorized amount by payment object
$unzer   = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$payment = $unzer->fetchPayment('s-pay-1');
$charge  = $payment->charge();
// part charge authorization by payment ID
$unzer   = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$charge1 = $unzer->chargeAuthorization('s-pay-1', 50.0);
$charge2 = $unzer->chargeAuthorization('s-pay-1', 50.0);
// part charge authorization by authorization object
$unzer         = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$authorization = $unzer->fetchAuthorization('s-pay-1');
$charge1 = $authorization->charge(50.0);
$charge2 = $authorization->charge(50.0);
// part charge authorization by payment object
$unzer   = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$payment = $unzer->fetchPayment('s-pay-1');
$charge1 = $payment->charge(50.0);
$charge2 = $payment->charge(50.0);

Arguments to Unzer::chargeAuthorization

Parameter Type Description
payment string or UnzerSDK\Resources\Payment The ID of the payment resource or the payment object itself can be entered here.
Required: true
amount float The amount to charge of the authorization. The method will perform a full charge of the authorization if the amount is not set.
Required: false
Default: null
orderId string The ID of the order in your store.
This ID can be used to fetch the payment resource from the PAPI using the method Unzer::fetchPaymentByOrderId($YourOrderId)
Required: false
Default: null
invoiceId string This is the invoiceId from your shop.
Required: false
Default: null

Arguments to Authorization::charge

Parameter Type Description
amount float The amount to charge of the authorization. The method will perform a full charge of the authorization if the amount is not set.
Required: false
Default: null

Arguments to Payment::charge

Parameter Type Description
amount float The amount to charge of the authorization. The method will perform a full charge of the authorization if the amount is not set.
Required: false
Default: null
currency string The currency of the amount.
Required: false
Default: null

Cancel on an Authorization (aka Reversal)

An cancellation transaction for an authorization transaction results in the creation of a cancellation resource linked to the original authorization resource. The cancel method has the parameter amount, which can be left empty to perform a full reversal of the authorization. If the amount is set the reversal will reduce the authorization total by the given amount.

// full cancel on Authorization
$unzer         = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$authorization = $unzer->fetchAuthorization('s-pay-1');
$cancellation  = $authorization->cancel();
// part cancel on Authorization
$unzer         = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$authorization = $unzer->fetchAuthorization('s-pay-1');
$cancellation  = $authorization->cancel(50.0);

Arguments to Authorization::cancel

Parameter Type Description
amount float The amount to reduce the authorization by. The method will perform a full cancel of the authorization (and payment) if the amount is not set.
Required: false
Default: null

Cancel on a Charge (aka Refund)

A cancel on a Charge transaction will result in the creation of a Cancellation resource linked to the original Charge resource. The cancel method has the amount parameter that can be left blank to perform a full refund of the charge. If the amount is set, the refund will reduce the charged total by the given amount.

$unzer  = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$charge = $unzer->fetchChargeById('s-pay-1', 's-chg-1');
$cancel = $charge->cancel();
$unzer  = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$charge = $unzer->fetchChargeById('s-pay-1', 's-chg-1');
$cancel = $charge->cancel(50.0);
$unzer   = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$payment = $unzer->fetchPayment('s-pay-1');
$cancel  = $payment->cancelAmount(59.5, null, 'Payment reference text', 50.0, 9.5);

Arguments to Charge::cancel

Parameter Type Description
amount float The amount to cancel. The method will perform a full cancel of the charge (and payment) if the amount is not set.
This is transmitted as amountGross in case of Unzer Instalment.
Required: false
Default: null
reasonCode string (heidelpayPHP\Constants\CancelReasonCodes) The reason why the charge amount is reduced/cancelled.
It can be one of the following:
‘CANCEL’, ‘RETURN’, ‘CREDIT’.
Required: in case of Invoice secured payment type
Default: null
paymentReference string The reference string is show to the customer as reference text on his bank statement.
Required: false
Default: null
amountNet float The net amount to cancel.
Required: only in case of Unzer Instalment.*
Default: null
amountVat float The VAT amount to cancel.
Required: only in case of Unzer Instalment.*
Default: null

Payout

This transaction credits an amount of money to a payment type without any reference to a previous payment transaction.

$unzer  = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$card   = $unzer->fetchPaymentType('s-crd-9wmri5mdlqps');
$payout = $unzer->payout(100.00, 'EUR', $card, 'https://your.return.url');
$unzer  = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$card   = $unzer->fetchPaymentType('s-crd-9wmri5mdlqps');
$payout = $card->payout(100.0, 'EUR', 'https://your.return.url', null, null, null, null, 'invoiceId', 'payment reference text');

The payout transaction is currently available for the following payment types:

  • Card
  • Unzer Direct Debit secured

Arguments to PaymentType::payout

Name Type Description
amount float The amount to credit the given payment type with.
Required: true
currency string The currency of the amount.
Required: true
returnUrl string A return URL (which is not used in this transaction).
customer string | UnzerSDK\Resources\Customer A reference to the customer resource corresponding to this transaction.
This can be either a customer object or the ID of an existing customer resource. If a customer object is used whose ID is not set (i. e. the resource does not exist yet in the PAPI) the customer resource will automatically be created and referenced with the transaction call.
Find additional information here.
Required: only in case of guaranteed payment types
Default: null
orderId string The ID of the order in your store.
Required: false
Default: null
metadata UnzerSDK\Resources\Metadata A reference to the metadata corresponding to this payment.
The metadata object can be used to pass along custom information which you whish to reference to the payment.
Find additional information here.
Required: false
Default: null
basket UnzerSDK\Resources\Basket A reference to the basket corresponding to this payment.
Find additional information here.
Required: false
Default: null
invoiceId string This is used to transmit the invoice ID from your shop to the API.
Required: false
Default: null
paymentReference string The reference string is show to the customer as reference text on his bank statement.
Required: false
Default: null
In case of secured payment methods (e. g. Unzer Direct Debit secured) the 4th parameter for payout transaction $customer is mandatory.

Shipment

A Ship transaction on a payment results in the creation of a shipment resource linked to the payment. The ship method on the Unzer object requires payment reference as parameter that is passed as an object or a as the payments ID string.

$unzer    = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$shipment = $unzer->ship('s-pay-1);
$unzer    = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$payment  = $unzer->fetchPayment('s-pay-1');
$shipment = $unzer->ship($payment);
$unzer    = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$payment  = $unzer->fetchPayment('s-pay-1');
$shipment = $payment->ship();

Arguments to Unzer::ship

Parameter Type Description
payment string | UnzerSDK\Resources\Payment The ID of the payment resource or the Payment object itself.
Required: true
invoiceId string The ID of the invoice in your shop. Only applicable in case of invoice payment types.
Required: In case of invoice payment types and if it has not been set before.
Default: null
orderId string The ID of the order in your store.
This ID can be used to fetch the payment resource from the PAPI using the method $unzer->fetchPaymentByOrderId($YourOrderId)
Required: false
Default: null

Arguments to Payment::ship

Parameter Type Description
invoiceId string The ID of the invoice in your shop. Only applicable in case of invoice payment types.
Required: In case of invoice payment types and if it has not been set before.
Default: null
orderId string The ID of the order in your store.
This ID can be used to fetch the payment resource from the PAPI using the method $unzer->fetchPaymentByOrderId($YourOrderId)
Required: false

Transaction Results

Transaction provide a message property holding the result of the last state change of the transaction. The message object stored here has a code and a message stored in the property customer.

The message can be used to give a specific reason for a state change e.g. as to why a transaction failed. The state of a transaction can change asynchronously e. g. from pending to successful or from pending to error. You can check the result of a transaction within a request in order to find out whether the payment was successful. Or fetch a transaction asynchronously to check the state and reason for the state the transaction is in.

$unzer     = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$authorize = $unzer->authorize(12.99, 'EUR', $paymentTypeId, 'https://your.return.url');

if (!$authorize->isError()) {
    $this->redirectToSuccess();
}
$this->log($authorize->getMessage()->getCustomer());
$this->redirectToFailure(); // redirect to the failure page of your shop