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.
`currency` (required)	string	The authorization currency, in the ISO 4217 alpha-3 format (for example, `EUR`)
`returnUrl` (required)	string	Required for redirect payments and credit card payments if 3-D Secure is used (for example, `https://www.unzer.com`)
`customerId`	string	The ID of the `customers` resource to be used (for example, `s-cst-3a0daffe47cb`)
`typeId` (required)	string	The ID of the payment type resource to be used (for example, `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, see the API reference guide.

Important information

Authorize a payment

Overview

Example

See also