Authorizations

The authorization (also authorization hold) process is an essential step in completing a card transaction. During authorization, the merchant receives the card holder’s information and verifies that the card is valid and that the card holder has sufficient funds to cover the amount of the transaction. Most merchants proceed immediately from authorization to the completion of the transaction, but they have the option to place a hold instead.

An authorization effectively “reserves” a certain amount of the card holder’s available funds for the merchant upon completion of the card transaction. The amount of the authorization is made unavailable to the card holder, but it isn’t transferred to the merchant’s account—not yet. When the transaction is settled, the authorization will be removed, and the card holder is charged the actual, final purchase amount.

Note

When using a card in gas stations, the authorization is made before the purchase amount is determined. In this case, a 100$ authorization and hold will be made (or of the current balance if it is lower than 100$) and any difference will be released once the purchase is settled.

The authorized amount will be included in the card holder account hold amount and will be reflected in the account available amount (see Deposit Account)

Authorization Statuses

Authorizations have a Status Property, which represent their current status.

Status	Description
Authorized	The authorization was created and is awaiting settlement.
Completed	The authorization was settled through a transaction.
Canceled	The authorization was reverted by the merchant or expired.
Declined	The authorization was declined, for example: due to insufficient funds.

Authorization Decline Reasons

Bellow is a list of the most common decline reasons.

Decline Reason	Description
CardVerificationValueFailed	Verification of CVV or CVV2 has failed.
IncorrectPIN	PIN verification failed.
ExceedsAmountLimit	The amount limit for the card or account has been exceeded.
InsufficientFunds	Transaction Amount exceeds the cardholders available balance or available credit limit.
RequestedFunctionNotSupported	A permanent restriction is placed, either account specific or broad level.
AllowablePINTriesExceeded	Defined number of PIN entry tries has been exceeded.
SuspectedFraud	The transaction does not pass risk monitoring detection systems.
ClosedAccount	The account is closed.
DoNotHonor	Generic Response Code.
CardholderBlocked	New card that has not been activated or has been temporarily blocked
CardStolen	The cardholder has reported the card stolen.
RestrictedCard	A transaction is attempted from a country where transactions are restricted, including OFAC or embargoed countries.
MerchantDenyList	Unit managed Merchant deny list
MccDenyList	Unit managed MCC deny list
CountryDenyList	Unit managed Country deny list

Get by Id

Get an authorization resource by id.

Verb	GET
URL	https://api.s.unit.sh/authorizations/{id}
Required Scope	authorizations
Timeout (Seconds)	5

Query Parameters

Name	Type	Default	Description
filter[includeNonAuthorized]	boolean	false	Optional. Include authorizations from all statuses.

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	Authorization	Authorization resource.

curl -X GET 'https://api.s.unit.sh/authorizations/1' \
-H "Authorization: Bearer ${TOKEN}"

List

List authorizations. Filtering and sorting can be applied. Paging is available only when filtering by customer id or account id.

Verb	GET
URL	https://api.s.unit.sh/authorizations
Required Scope	authorizations
Timeout (Seconds)	5

Query Parameters

Name	Type	Default	Description
page[limit]	integer	100	Optional. Maximum number of resources that will be returned. Maximum is 1000 resources.
page[offset]	integer	0	Optional. Number of resources to skip.
filter[accountId]	string	(empty)	Optional. Filters the results by the specified account id.
filter[accountType]	string	(empty)	Optional. Filter the results by account type (deposit, credit).
filter[customerId]	string	(empty)	Optional. Filters the results by the specified customer id.
filter[cardId]	string	(empty)	Optional. Filters the results by the specified card id.
filter[since]	RFC3339 Date string	(empty)	Optional. Filters the Authorizations that occurred after the specified date. e.g. 2020-01-13T16:01:19.346Z
filter[until]	RFC3339 Date string	(empty)	Optional. Filters the Authorizations that occurred before the specified date. e.g. 2020-01-02T20:06:23.486Z
filter[includeNonAuthorized]	boolean	false	Optional. Include authorizations from all statuses.
filter[status]	string	Authorized	Optional. Filter authorizations by Authorization Status.
filter[merchantCategoryCode][]	Integer	(empty)	Optional. Filter authorizations by their 4-digit ISO 18245 merchant category code (MCC).
filter[fromAmount]	Integer	(empty)	Optional. Filters the Authorizations that have an amount that is higher or equal to the specified amount (in cents). e.g. 5000
filter[toAmount]	Integer	(empty)	Optional. Filters the Authorizations that have an amount that is lower or equal to the specified amount (in cents). e.g. 7000
sort	string	sort=-createdAt	Optional. Leave empty or provide sort=createdAt for ascending order. Provide sort=-createdAt (leading minus sign) for descending order.

curl -X GET 'https://api.s.unit.sh/authorizations?page[limit]=20&page[offset]=0' \
-H "Authorization: Bearer ${TOKEN}"

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	Array of Authorization	Array of authorization resources.
meta	JSON object that contains pagination data	Optional. Will be defined only when filtered by customer or account id. Pagination data includes offset, limit and total (estimated total items).

Example Response:

{
  "data": [
    {
      "type": "authorization",
      "id": "90",
      "attributes": {
        "createdAt": "2021-02-16T07:40:44.970Z",
        "amount": 2000,
        "cardLast4Digits": "",
        "merchant": {
          "name": "Europcar Mobility Group",
          "type": 3381,
          "category": "EUROP CAR",
          "location": "Cupertino, CA",
          "id": "029859000085093"
        }
      },
      "relationships": {
        "customer": {
          "data": {
            "type": "customer",
            "id": "10000"
          }
        },
        "account": {
          "data": {
            "type": "account",
            "id": "10001"
          }
        },
        "card": {
          "data": {
            "type": "card",
            "id": "10501"
          }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "limit": 100,
      "offset": 0
    }
  }
}