Skip to main content

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.

StatusDescription
AuthorizedThe authorization was created and is awaiting settlement.
CompletedThe authorization was settled through a transaction.
CanceledThe authorization was reverted by the merchant or expired.
DeclinedThe authorization was declined, for example: due to insufficient funds.

Authorization Decline Reasons#

Decline ReasonDescription
CardVerificationValueFailedVerification of CVV or CVV2 has failed.
IncorrectPINPIN verification failed.
ExceedsAmountLimitThe amount limit for the card or account has been exceeded.
InsufficientFundsTransaction Amount exceeds the cardholders available balance.
RequestedFunctionNotSupportedA permanent restriction is placed, either account specific or broad level.
AllowablePINTriesExceededDefined number of PIN entry tries has been exceeded.
SuspectedFraudThe transaction does not pass risk monitoring detection systems.
ClosedAccountThe account is closed.
DoNotHonorGeneric Response Code.
CardholderBlockedNew card that has not been activated or has been temporarily blocked
CardStolenThe cardholder has reported the card stolen.

Get by Id#

Get an authorization resource by id.

VerbGET
Urlhttps://api.s.unit.sh/authorizations/{id}
Required Scopeauthorizations

Query Parameters#

NameTypeDefaultDescription
filter[includeNonAuthorized]booleanfalseOptional. Include authorizations from all statuses.

Response#

Response is a JSON:API document.

200 OK#

FieldTypeDescription
dataAuthorizationAuthorization 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.

VerbGET
Urlhttps://api.s.unit.sh/authorizations
Required Scopeauthorizations

Query Parameters#

NameTypeDefaultDescription
page[limit]integer100Optional. Maximum number of resources that will be returned. Maximum is 1000 resources.
page[offset]integer0Optional. Number of resources to skip.
filter[accountId]string(empty)Optional. Filters the results by the specified account id.
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]booleanfalseOptional. Include authorizations from all statuses.
filter[status]stringAuthorizedOptional. 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
sortstringsort=-createdAtOptional. 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#

FieldTypeDescription
dataArray of AuthorizationArray of authorization resources.
metaJSON object that contains pagination dataOptional. Will be defined only when filtered by customer or account id. Pagination data includes offset, limit and total (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"        }      },      "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    }  }}