Authorize a payment

Reserve money on the customer’s 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 transaction calls on a payment type require at least the amount, the currency and the returnUrl.

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

$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::authorize

Parameter	Type	Description
amount	float	The amount to be authorized Required: true
currency	string	The currency of the amount. Required: true
paymentType	string \| `BasePaymentType`	The PaymentType object or the id of the PaymentType to use. `charge` function of payment types don’t have this parameter, the other parameters are the same, though. Required: true
returnUrl	string	The URL the customer will be redirected to after a transaction. This needs to be set to a valid URL, no matter whether a redirect is necessary or not. Required: true
customer	string \| `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 (that is, the resource does not exist yet in the Payment API) the customer resource will automatically be created and referenced with the transaction call. For more details, see Manage customer 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 wish to reference to the payment. Find more details, see Manage metadata. Required: false Default: null
basket	`UnzerSDK\Resources\Basket`	A reference to the basket corresponding to this payment. For more details, see Manage baskets 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 Unzer Invoice Secured 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
recurrenceType	string	Recurrence type used for recurring payment. Required: false Default: null

Arguments to authorize of payment type

Parameter	Type	Description
amount	float	The amount to be charged Required: true
currency	string	The currency of the amount. Required: true
returnUrl	string	The URL the customer will be redirected to after a transaction. This needs to be set to a valid URL, no matter whether a redirect is necessary or not. Required: true
customer	string \| `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. For more details, see Manage customer. 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 wish to reference to the payment. Find more details, see Manage metadata. Required: false Default: null
basket	`UnzerSDK\Resources\Basket`	A reference to the basket corresponding to this payment. For more details, see Manage baskets 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 Unzer Invoice Secured 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
recurrenceType	string	Recurrence type used for recurring payment. Required: false Default: null

Transaction results

The transaction response will be stored in the transaction object. It contains a paymentId (e.g s-pay-1) the transactionId and other properties of the response. The transaction object provides getter functions to access those properties. E.g. $authorize->getPaymentId()

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

If a transaction fails, the payment API will return an error resource instead of a transaction. In the SDK this is handled as an UnzerApiException. Make sure to catch that case properly.

You can find an example transaction response on the Authorize a payment page inside direct API integration.

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

    if ($authorize->isSuccess) {
        $this->redirectToSuccess();
    }
    // Transaction has to be pending at this point.
    $this->redirectToPending(); // Handle pending transaction
} catch (UnzerApiException $e) {
    // Transaction failed. API returned error resource.
    $this->log($e->getClientMessage());
    $this->log($e->getMerchantMessage());
    $this->redirectToFailure(); // Redirect to the failure page of your shop
} catch (RuntimeException $e) {
    $merchantMessage = $e->getMessage();
}