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

Authorization is triggered by calling  payments/authorize endpoint.

POST https://api.unzer.com/v1/payments/authorize
{
  "amount" : "100.00",
  "currency" : "EUR",
  "returnUrl": "https://www.unzer.com",
  "resources" : {
    "customerId" : "s-cst-3a0daffe47cb",
    "typeId" : "`s-crd-fm7tifzkqewy"
  }
}
Parameter Type Description
amount (required) Float The authorization amount (e.g. 12.23)
currency (required) String The authorization currency, in the ISO 4217 alpha-3 format (e.g. EUR)
returnUrl (required) String Required for redirect payments and credit card payments if 3-D Secure is used (e.g. https://www.unzer.com)
customerId String The ID of the customers resource to be used (e.g. s-cst-3a0daffe47cb)
typeId (required) String The ID of the payment type resource to be used (e.g. s-crd-fm7tifzkqewy)

An authorize call returns a payment ID 1 (s-pay-1) and the authorization ID 1 (s-aut-1) because only one authorization per payment is possible.

{
    "id": "s-aut-1",
    "isSuccess": true,
    "isPending": false,
    "isError": false,
    "message": {
        "code": "COR.000.100.112",
        "customer": "Request successfully processed in 'Merchant in Connector Test Mode'"
    },
    "amount": "100.0000",
    "currency": "EUR",
    "returnUrl": "https://www.unzer.com",
    "paymentReference": "Test authorize transaction",
    "date": "2018-09-13 19:41:49",
    "resources": {
        "customerId": "s-cst-3a0daffe47cb",
        "basketId": "",
        "paymentId": "s-pay-1",
        "metadataId": "",
        "traceId": "bf4ce634575d479eaaac4e6ad436d95d",
        "typeId": "s-crd-fm7tifzkqewy"
    },
    "processing": {
        "uniqueId": "31HA07BC8179DC97ADB6249F09E3BBBE",
        "shortId": "4007.9410.9870",
        "3dsecure": false // only for the card payment method
    }
}

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

Status parameter Description
isSuccess The authorize call was executed successfully.
isPending The customer must be forwarded to the redirectUrl so that the payment can be completed. The payment method determines whether an authorize call can enter the pending state.
isError Something went wrong. message.merchant contains more information about the problem.
Parameter Type Description
id string The authorization’s unique ID.
isSuccess boolean If the transaction was successful, the value is set to true.
isPending boolean If the transaction is pending, the value is set to true, for example, if a redirect to an external system is required.
isError boolean If an error occurs, this value is set to true.
redirectUrl string If the customer’s confirmation is required, a redirect URL will be returned. Customer needs to be redirected to this URL and proceed with the confirmation.
message object
message.code string A 9-digit code returned with every API call.
message.customer string Response message for your customer translated into the customer language.
message.merchant string Response message for you. This message appears always in English.
amount string The amount to be authorized on the specified account. The amount is rounded depending on the respective currency.
currency string(3) ISO currency code: For a list of possible codes, see Amounts and Currencies.
returnUrl string The URL the customer will be redirected to after a transaction.
paymentReference string The description of the transaction.
date date Timestamp of this transaction.
resources object
resources.customerId string Customer ID used for this transaction.
resource.basketId string The basket ID used for this transaction.
resource.metadataId string The metadata ID used for this transaction.
resources.paymentId string ID of the payment.
resources.traceId string The unique traceId of the transaction. Used for internal API purposes.
resources.typeId string ID of the types Resource that is to be used for this transaction.
processing object
processing.uniqueId string Unique ID of the payment system used.
processing.shortId string The reference ID of the payment system.
processing.3dsecure boolean Indicates a 3DS transaction (card payment type only).

For a full description of the Authorize call, please refer to API reference guide.

See also