Authorize a payment

Reserve money on the customer’s payment account.

Overview

The authorization call verifies payment details and checks for sufficient funds on the customer account. If the check is successful, the funds are reserved for at least 7 days. If the authorization is not debited within this period, the authorization expires and the amount is released.

The authorization does not trigger a debit transaction. It only reserves the amount for the customer’s payment type. To execute money transfer you have to perform a charge after authorization.

This transaction is possible for selected payment methods only. For more details, see Payment methods.

Example

In general, the authorization call on a payment type instance requires at least the amount, the currency and the returnUrl.

$unzer     = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');

$authorizationInstance = new Authorization(100.00, 'EUR', $returnUrl);
$transaction = $unzer->performAuthorization($authorizationInstance, 's-crd-9wmri5mdlqps');

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

Arguments to Unzer::performAuthorization

Properties of Authorization for Payment requests

The list below contains properties that are relevant for an authorization transaction.

For a full list of the authorize request parameter, please refer to API reference.

Additional transaction Data

For some transactions it can be necessary to set additionalTransactionData, in general these can be added to a Charge or Authorization transaction using the addAdditionalTransactinData($key, $value) method when needed. For specific fields extra setter methods are provided. Examples can be found below:

Setting card data PHP-SDK provides extra setter for setting card’s recurrenceType :

// create auth/charge transaction object...
$transaction->setRecurrenceType(RecurrenceTypes::ONE_CLICK);
// perform transaction ...

// create auth/charge transaction object...
$cardData = (new \UnzerSDK\Resources\EmbeddedResources\CardTransactionData())
  ->setRecurrenceType(RecurrenceTypes::ONE_CLICK)
  ->setExemptionType(ExemptionType::LOW_VALUE_PAYMENT);
  
$transaction->setCardTransactionData($cardData);
// perform transaction ...

Setting shipping data

// create auth/charge transaction object...
$shipping = (new ShippingData())
    ->setDeliveryService('deliveryService')
    ->setDeliveryTrackingId('deliveryTrackingId')
    ->setReturnTrackingId('returnTrackingId');

$transaction->setShipping($shipping);
// perform transaction ...

Setting riskData

// create auth/charge transaction object...
$riskData = (new RiskData())
    ->setThreatMetrixId('f544if49wo4f74ef1x')
    ->setCustomerGroup('TOP')
    ->setCustomerId('C-122345')
    ->setConfirmedAmount('1234')
    ->setConfirmedOrders('42')
    ->setRegistrationLevel('1')
    ->setRegistrationDate('20160412');


$transaction->setRiskData($riskData);
// perform transaction ...

[Deprecated] Arguments to Unzer::authorize

Arguments to authorize of payment type instance

• If an object is used, the ID for which is not set (the resource is currently not available in the Unzer API), the customer resource is automatically created and referenced with the transaction call.

Transaction results

The authorization object is updated with the data from the Unzer API response. It contains the paymentId (for example, s-pay-1), the transactionId, and other properties. The transaction object provides getter functions to access these properties.

The properties isSuccess, isPending and isError indicate the result of the transaction. Only one of these three can be true.

If the transaction fails, the Unzer API returns an error resource. In the SDK, this is handled as an UnzerSDK\Exceptions\UnzerApiException. Make sure to catch the exception type and handle it as properly.

For an example transaction, see Authorize a payment.

try {
    $unzer     = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
    
    $authorizationInstance = new Authorization(100.00, 'EUR', $returnUrl);
    $transaction = $unzer->performAuthorization($authorizationInstance, 's-crd-9wmri5mdlqps');

    if ($transaction->isSuccess) {
        $this->handleSuccessState(); // for example, redirect to the success page in your shop
    }
    // Transaction has to be pending at this point.
    $this->handlePendingState(); // for example, redirect to the pending page in your shop
} catch (UnzerApiException $e) {
    // Transaction failed. API returned error resource.
    $this->log($e->getClientMessage());
    $this->log($e->getMerchantMessage());
    $this->handleFailureState(); // for example, redirect to the failure page of your shop
} catch (RuntimeException $e) {
    $merchantMessage = $e->getMessage();
}

See also

• Charge a payment
• Cancel an authorization (reversal)