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.
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');
$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 (required) |
float | The amount to be authorized. |
currency (required) |
string | The currency of the amount. |
paymentType (required) |
string | The payment type object or the ID of the payment type to use. |
returnUrl (required) |
string | The URL to which the customer will be redirected, after the transaction is complete. |
customer |
string | 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. |
orderId |
string | The ID of the order in your store. This ID can be used later to fetch the payment resource from the API using the method Unzer::fetchPaymentByOrderId("myId123") |
metadata |
string | 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. For more details, see Manage metadata. |
basket |
string | A reference to the basket corresponding to this payment. For more details, see Manage baskets. |
card3ds |
boolean | Allows to switch between a 3DS and non-3DS channel, if both are configured for the merchant. Otherwise it will be ignored. |
invoiceId |
string | This is used to transmit the invoice ID from your shop to the API. The invoice ID is required for Unzer Invoice Secured payment, however it can also be transmitted later with the shipment call. |
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. |
recurrenceType |
string | Recurrence type used for recurring payment. Available values: scheduled, unscheduled, oneclick |
Arguments to authorize of payment type instance
Parameter | Type | Description |
---|---|---|
amount (required) |
float | The amount to be reserved on the customers payment account. |
currency (required) |
string | The currency of the amount. |
returnUrl | string | The URL to which the customer will be redirected, after the transaction is complete. This needs to be set to a valid URL, no matter whether a redirect is necessary or not. |
customer |
string | A reference to the customer resource corresponding to this payment. For more details, see Manage customer. |
orderId (required) |
string | The ID of the order in your store. This ID can be used later to fetch the payment resource from API using the method Unzer::fetchPaymentByOrderId("myId123") |
metadata |
string | 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. For more details, see Manage metadata. |
basket | string | A reference to the basket corresponding to this payment. For more details, see Manage baskets. |
card3ds | boolean | Allows to switch between a 3DS and non-3DS channel, if both are configured for the merchant. Otherwise, it is ignored. |
invoiceId |
string | This is used to transmit the invoice ID from your shop to the API. The invoice ID is necessary in case of Unzer Invoice Secured payment, however it can also be transmitted later with the shipment call. |
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. |
recurrenceType |
string | Recurrence type used for recurring payment. Available values: scheduled, unscheduled, one-click |
Transaction results
The authorization object is updated with the data from the PAPI response. It contains the paymentId
(e.g s-pay-1
) the transactionId
and other properties. The transaction object provides getter functions to access those 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 payment API will return 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.
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->handleSuccessState(); // e.g. redirect to the success page in your shop
}
// Transaction has to be pending at this point.
$this->handlePendingState(); // e.g. 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(); // e.g. redirect to the failure page of your shop
} catch (RuntimeException $e) {
$merchantMessage = $e->getMessage();
}