alt

Important information

Please be advised that there will be a scheduled downtime across our API network on November 05 and November 07, 2024. For more information, visit our platform status portal.:
- Scheduled maintenance on November 5, 2024
- Scheduled maintenance on November 7, 2024

Unzer

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.

icon info
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.

Option 1: Authorize using an Unzer object

// basic charge example
Unzer unzer  = new Unzer("s-priv-xxxxxxxxxx");
Authorize authorize = unzer.authorize(BigDecimal.valueOf(12.99), Currency.getInstance("EUR"), "s-crd-9wmri5mdlqps", "https://your.return.url");

Option 2: Authorize using payment type object

// basic charge example
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Card card = (Card) unzer.fetchPaymentType("s-crd-9wmri5mdlqps");
Authorize authorize = card.authorize(BigDecimal.valueOf(12.99), Currency.getInstance("EUR"), "https://your.return.url");

Arguments to Unzer.authorize

ParameterTypeDescription
amount
(required)
floatThe amount to be authorized.
currency
(required)
stringThe currency of the amount.
paymentType
(required)
stringThe payment type object or the ID of the payment type to use.
returnUrl
(required)
stringThe URL to which the customer will be redirected, after the transaction is complete.
customer*stringA reference to the customer resource corresponding to this payment.
This can be either a customer object or the ID of an existing customer resource.
For more details, see Manage customer.
orderIdstringThe 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*stringA 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*stringA reference to the basket corresponding to this payment.
For more details, see Manage baskets.
card3ds (Deprecated)booleanAllows to switch between a 3DS and non-3DS channel, if both are configured for the merchant. Otherwise it will be ignored.
invoiceIdstringThis is used to transmit the invoice ID from your shop to the API.
Maximum length: 16 characters
paymentReferencestringThis is a reference string to show the customer the purpose of the transaction. This will be shown on the bank statement of the buyer.
recurrenceTypestringRecurrence type used for recurring payment.
Available values: scheduled, unscheduled, one click
* 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.

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

Arguments to authorize of payment type

ParameterTypeDescription
amount
(required)
BigDecimalThe transaction amount to be charged
currency
(required)
CurrencyThe currency of the amount.
returnUrl
(required)
URLThe 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.
customerCustomerA reference to the customer resource corresponding to this payment.
This can either be a customer object or the ID of an existing customer resource. If there is no customer resource available, an ID is automatically created and referenced in this transaction call.
For more details, see Manage customer

Transaction results

The authorization object is updated with the data from the Unzer API 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 status indicates the result of the transaction. Possible values: SUCCESS, PENDING, or ERROR.

If the transaction fails, the Unzer API returns an error resource. In the SDK this is handled as an UnzerPaymentException. 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 unzer  = new Unzer("s-priv-xxxxxxxxxx");
    Authorize authorize = unzer.authorize(BigDecimal.valueOf(12.99), Currency.getInstance("EUR"), "s-crd-9wmri5mdlqps", "https://your.return.url");

    if (authorize.Status.equals(Authorize.Status.SUCCESS)) {
        this.redirectToSuccess();
    }
    // Transaction has to be pending at this point.
    this.redirectToPending();
} catch (HttpCommunicationException | PaymentException e) {
    // Transaction failed. API returned error resource.
    List<PaymentError> paymentErrorList = e.getPaymentErrorList();
    //Handle API Errors
    
    this.redirectToFailure(); // redirect to the failure page of your shop
} catch (Exception e) {
    merchantMessage = e.getMessage();
}

See also