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.
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. |
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 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). |
{
"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
}
}
}