Authorize a payment

Reserve money on the customer’s account.

Overview

The authorization call verifies the payment details and checks if there are sufficient funds on the customer account. If the check is successful, the funds are reserved for up to 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.

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

Parameter Type Description
amount BigDecimal The amount that should be authorized.
Required: true
currency Currency The currency of the amount.
Required: true
paymentType string | PaymentType The PaymentType object or the ID of the PaymentType to use.

The charge function of payment types don’t have this parameter. The rest of the other parameters are the same.

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 | Customer A 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 a customer object is used, the ID for which is not set (that is, the resource does not exist yet in the PAPI), the customer resource is automatically 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.
Required: false
Default: null
metadataId string A reference to the metadata corresponding to this payment.
The metadata object can be used to pass along custom information that you wish to reference to the payment.
Find more details, see Manage metadata
Required: false
Default: null
basket 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 is 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 is shown on the bank statement of the buyer.
Required: false
Default: null
recurrenceType string Recurrence type used for the recurring payment.

Required: false
Default: null

Arguments to authorize of payment type

Parameter Type Description
amount BigDecimal The amount to be charged
Required: true
currency Currency 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 Customer

Transaction results

The transaction response is stored in the transaction object. It contains a paymentId (for example, 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 status-parameter indicate the result of the transaction. The Enum can only be SUCCESS, PENDING, or ERRROR

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

To see an example of the transaction response, go to Authorize a payment.

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