This guide explains authorization in depth. Before reading this guide you should be familiar with the concepts in these guides:
- About Transactions — A general guide to how transactions are represented in the Galileo system.
- About Card Transactions — A general overview of how card transactions work, including the phases that a card transaction passes through.
For information on the Auth API, see the Authorization Controller API guide.
To see detailed examples of transaction sequences as they appear in the Program API, Events API, Auth API, and RDFs, consult the Card Transaction Scenarios.
Authorization and preauthorization
An authorization request may be one of two types: authorization or preauthorization.
Authorization and preauthorization are similar in that they both request that the issuer approve a transaction amount. They are different in that merchants request authorization when the total sale amount is known and preauthorization when the sale amount is estimated.
Because the preauthorization is an estimate, the difference between the preauthorized amount and the final sale amount can vary widely. Some merchants preauthorize an amount that is far higher than the probable sale amount so that they can be guaranteed payment no matter what the total turns out to be. Other merchants preauthorize the known sale amount but anticipate adding costs later.
Preauthorizations are typically requested under these circumstances:
- A gas pump doesn't have the total sale amount until after the gas is dispensed.
- A car rental agency wants to cover the cost of a delayed return of the car, plus other unforeseeable costs.
- A hotel knows the cost of the room but doesn't know whether the minibar or other features will be accessed until checkout.
- A restaurant assumes that a tip will be added to the receipt.
- An online retailer knows the sale amount of the goods but does not know the shipment amount until after the order is processed at the warehouse.
- An online retailer preauthorizes $1 to check if the card is valid, and then immediately reverses the preauthorization.
Galileo identifies preauthorizations based on information in the authorization request, and each network uses a different method to identify a preauthorization. Preauthorizations are not differentiated from authorizations in the Authorized Transactions RDF. However, a preauthorization is transaction type
L in the Program API and Events API and authorizations are transaction type
A, so a preauthorization over Mastercard Banknet rails has the transaction code
AUL, over Maestro rails it is
DBL and over Visa and Interlink rails it is
VIL. For authorizations the codes would be
See the Transaction Types enumeration for all authorization-related transaction codes.
When the purchase amount is known, the merchant sends one of two message types:
- Completion — Using an advice message type, the merchant informs the issuer of the actual purchase amount. Completions arrive directly through the authorization stream, and then later are followed by a clearing message in the batch file from the network. See Completion in the Settlement guide for more information.
- Clearing/settlement — The merchant sends a conventional clearing message after a preauthorization instead of a completion. See the Settlement guide for more information.
When Galileo receives an authorization or a preauthorization request, it performs checks on the card and its account. According to the results of those checks, Galileo returns a response code to the merchant, indicating either that the request has been approved or denied, and if denied, the reason for the denial.
The full list of response codes are in the Authorization Response Codes enumeration. Also consult the Auth API Validation Checks guide for a detailed description of the checks.
You can see the response code that Galileo returns in the these places:
response_codefield in Authorization Events API webhooks
- Get All Transaction History endpoint response (
deny_codefield, for denials only)
AUTHORIZATION RESPONSEfield in the Authorized Transactions RDF
You can be involved in the authorization process by using the Authorization Controller API (Auth API), which gives you the ability to override some response codes after Galileo has performed its checks. Contact Galileo for information on implementing the Auth API.
Besides authorizations and preauthorizations, you will encounter these variants on authorizations:
- Upcharges, below
- Partial authorizations
- AVS-only checks
- Bulk authorization
- Provisioning requests
- Balance inquiries
For some merchant types there is a high likelihood that the clearing amount will be higher than the preauthorization amount, such as with gas pumps and merchants that add a tip after getting preauthorization. For these merchant types an issuer can decide to preauthorize only the requested amount plus a fixed percentage as an upcharge. For example, if a restaurant submits a preauthorization request for $50, the issuer can decide to approve the transaction only if the cardholder account contains the authorization amount plus 20%, or $60.
Using this method carries some risk of a negative cardholder experience if, for example, the transaction is declined when the cardholder has $10 cash for the tip and knows there is $50 in the account to cover the bill.
In the case of gas stations, some pumps send a preauthorization request for a high anticipated sale amount, whereas others request only $1 to verify that the card is active. An issuer can decide to add a significant upcharge to $1 gas-pump requests; an upcharge of $75 or $100 is not unusual. In the case that both the pump and the issuer have assigned upcharges to the transaction, the upcharge that is highest is used.
Some merchants permit partial authorizations, which means that the issuer can authorize an amount that is less than the amount in an authorization request, and the merchant completes the transaction for only that amount.
For example, a cardholder inserts a card into a gas-pump reader. The merchant has configured the pump to request a $75 preauthorization and to accept partial authorizations. The cardholder has $30 in available funds. Rather than deny the preauthorization request for insufficient funds, the issuer authorizes a $30 purchase. The gas pump permits the cardholder to dispense exactly $30 worth of gasoline, then shuts off.
Partial authorizations also permit a cardholder to use multiple payment methods at the point of sale. For example, for a $50 purchase a cardholder might first present a $20 gift card, which is authorized for part of the sale price, and then present another card or cash for the remainder.
Merchants determine whether they accept partial authorizations, and this decision is communicated in the authorization request. Galileo then indicates the amount of the partial authorization in the authorization approval message and responds with code
Online merchants, both on web sites and in phone apps, often perform an AVS-only check at checkout time to verify that the card is valid and active, and then if the check passes, authorize the full sale amount afterwards. Other AVS-only checks happen when a cardholder adds a card in a mobile wallet as a payment method in an app.
The cardholder typically enters an address during checkout, or the information is obtained from the mobile wallet, and the merchant passes the first address line and/or zip code in the request, which is for 0.00. Galileo verifies that the information matches its records and returns a single-letter code to indicate what matched, if anything, along with a response code that indicates whether the card is valid and active.
AVS check responses
|Address and zip code match|
|Only the address matches|
|Only the zip code matches|
|Neither address or zip code match|
|AVS not used|
|Unrecognized AVS return value|
When an AVS-only check is successful, Galileo returns response code
85, which means it was a successful non-financial transaction. This response should not be confused with an
85 that is returned for provisioning requests that enter the yellow path.
The AVS score is independent of the response code. It is possible for Galileo to return an
N for the AVS check with
85 as the response code, which means that none of the address information matched but the card is otherwise valid. Merchants can decide whether to proceed with the transaction in this case. With small amounts a merchant may decide to continue with the sale. It is also possible for Galileo to return a
05, meaning that the address information matched but the transaction is denied for another reason.
After a successful AVS-only check for 0.00, a merchant sends an authorization request for the actual sale amount. There is no identifier to tie the AVS-only check with the subsequent sale-amount authorization.
Merchants can also request AVS checks when authorizing a non-zero sale amount: in that case, a successful AVS check is
Y and the response code is
00, assuming that the transaction is otherwise valid.
When Galileo returns
00, the transaction is visible in the Authorized Transactions RDF and an
auth event webhook is sent, but the approved transaction is not visible in the CST or Program API. Denied AVS checks (
05 or other), however, are available in the CST and Program API, and a deny-type event webhook is sent, depending on the reason for the denial.
If you do not want AVS checks for your product, such as for gift cards, set the NOAVS product parameter.
Some high-volume online merchants first perform an AVS-only check at purchase time to verify that the card is active. The merchant then sends authorization requests for sale amounts to the networks in bulk, which means that there can be a several-hour delay between the AVS check and the authorization for the sale amount.
From the cardholder's perspective the purchase is successful; however, the AVS check was for 0.00, and so the merchant has not yet received an authorization for the actual sale amount. If the merchant attempts to authorize the sale amount and the authorization is denied for insufficient funds, the merchant will likely cancel the transaction.
When a cardholder manually provisions a card to a mobile wallet, the wallet sends an authorization request to Galileo to verify that the card is valid. (With push-provisioning the cardholder is already validated.) These requests are for 0.00 and may or may not have an AVS check with them. Galileo responds with one of these codes:
00— Green path. Provisioning is approved.
85— Yellow path. Cardholder must provide additional verification.
05— Red path. Card cannot be provisioned.
These requests are visible in the Authorized Transactions RDF, and Galileo sends the
AAAU: auth webhook, by request.
For more information on these checks see the Manual provisioning workflow in the Setup for Mobile Wallets guide.
When an ATM sends an authorization request, the request includes all of the fees that are assessed by the ATM operator, the network, and by your program. If, for example, the ATM operator charges $2 per withdrawal and you assess a $3 fee, an authorization request for a $60 withdrawal would be for 65.00.
ATM withdrawal requests have transaction type
W for both the authorization and the settlement. For example, the transaction code for an ATM withdrawal authorization over Maestro rails is
DBW and its settlement is
With ATMs and with some other purchases, a cardholder can make a balance inquiry so that the current balance is displayed on the ATM screen or is printed on a receipt. These inquiries are visible in the Authorized Transactions RDF, and you can also request that the
AABI: bal event be sent. The transaction type for a balance inquiry at an ATM is
10 in the Authorized Transactions RDF) and the amount is 0.00. You can determine how to respond to balance inquiries on a per-MCC basis.
For examples see ATM withdrawal in Card Transaction Examples and these other scenarios:
Some authorization requests need to reference a previous authorization. The previous authorization is linked to the current authorization by a linking identifier. See Linking transactions in the About Transactions guide for an explanation of these identifiers.
Linking to a previous authorization is typically done in these scenarios:
- Reversals — When a merchant reverses out a transaction before it clears, the reversal message contains the ID of the authorization to reverse, whether a full or partial reversal. See Reversals in the Crediting Cardholder Accounts guide for more information.
- Completions — When a merchant sends a completion, the completion contains the ID of the preauthorization. See Completion in the Settlement guide for more information.
- Incremental authorizations — The merchant wants to add an amount (or more than one amount) to a previous authorization, so that the amounts are all part of the same authorization. Each incremental authorization contains the authorization ID of the previous increment. See Incremental authorizations, below, for details.
In some cases the merchant knows part of the sale amount at the time of authorization but must add charges after the original authorization is obtained. If the amount of the additional charge exceeds a certain threshold, the merchant must obtain another authorization. The threshold amount is determined by acquirers and networks and reflects the amount of risk they want to assume for unauthorized amounts.
For example, a cardholder may use a ride-share company for a ride that has multiple legs: after arriving at each destination, the cardholder asks to go to another destination. The ride-share app sends incremental authorizations for each leg of the ride, and Galileo replaces the previous hold with a new one for the cumulative amount. The app then sends a single clearing message for all of the rides together.
In other cases a merchant knows the sale amount for an item but does not know the shipping charges until a time later than the initial authorization. The merchant then adds a second authorization to the first and clears both authorizations with the same message.
For each incremental authorization, Galileo sends a
BAUT: auth webhook that contains the
auth_id of the previous authorization in the sequence in the
For examples see the Incremental authorization example in Card Transactions Examples and Scenario 3: Incremental authorizations
A new authorization record in Galileo's databases is considered pending until one of two events happens: settlement/completion or expiry. Settlement and completion are described in the Settlement guide.
When you set up your program, you determine how long an authorization remains pending until it expires. You can specify different expiry intervals depending on the authorization amount or the merchant type. For example, you could specify that an authorization at a hotel expires after 30 days, authorizations for small amounts after two days, and general authorizations after seven.
Galileo has automated processes that expire an authorization after the specified time. After an authorization is expired in this way, the authorization can no longer be matched with a settlement (which arrives through a settlement batch file) or with a completion (which arrives through the authorization stream).
For example, a merchant might get an authorization on the 10th of the month, and that type of authorization is set to expire after seven days. If the merchant or acquirer does not send clearing information to the network before the 17th, the authorization expires in Galileo's database and the purchase amount is returned to the cardholder's available balance. Galileo sends a
BEXP: auth_exp webhook.
Then, if the merchant tries to clear the transaction after the expiry, Galileo creates a new authorization entry that is immediately backed out and settled. (Because the authorization amount was returned back to the cardholder's available balance, there is a risk that a late-arriving settlement/completion could drive the account negative.) For this type of event you would receive only the
SETL: setl webhook.
When an authorization is reversed before clearing, both the authorization and reversal are pending until the expiry time elapses. See Reversals in the Crediting Cardholder Accounts guide for more information.
When a merchant obtains an authorization, the amount in the authorization request is the amount in the cardholder account's local currency. For example, if a cardholder who resides in Alabama goes to a gift shop in Rome, and the sale total is 50 Euros, the authorization amount will be expressed in the equivalent number of dollars, according to the exchange rate at the time of the authorization. The amount in the merchant's local currency is communicated in the
local_amt field in the Program API and
local_currency_amount in the Auth API. You can also request to have this information included in the Authorized Transactions and Posted Transactions RDFs.
Card networks typically charge extra for international transactions, and the amount is billed in a separate invoice instead of being included with the authorization amount.
Authorizations in the Program API
When Galileo sends an authorization response, a record is created that you can retrieve using the Program API. These endpoints return authorization information:
- Get Authorization History — Returns only unsettled, uncompleted, and unexpired authorizations
- Get Account Overview — Returns unsettled, uncompleted, and unexpired authorizations in the
authorizationsobject of the response.
- Get All Transaction History — Returns all transactions: settled, unsettled, unexpired, uncompleted, and completed as well as backouts
See Obtaining transaction history via API in the Transaction History guide for the use cases for each endpoint.
Authorized Transactions RDF
The Authorized Transactions RDF contains activity in the authorization stream during a 24-hour period. You can also request that Galileo send you the Expired Auth CDF. For more information see About RDFs and CDFs.
To see an authorization in a Program API response and an explanation of the fields, open this Recipe:
Authorization Events messages
Authorization-related webhooks are sent to the Authorization Events endpoint. Consult the Authorization Events Index for the list and About the Events API for general information.
There are two types of
auth event, known by the codes
AAAU. These codes are visible primarily in the Customer Service Tool (CST) in the Alerts log. The webhook itself does not contain the four-letter code except by request (
AAAU is sent at the same time as the response to these authorization messages:
- Completions (advice)
- Reversal notifications
- AVS-only checks
- Yellow-path tokenization requests
BAUT is sent for all other authorization requests except these
AABI: bal— Balance inquiries. This event is sent to the Account Events endpoint because it does not affect the available balance.
AAPM: auth_payment— Card loads
To see examples of transaction sequences with Events API webhooks, see Authorization events in the Events API Scenarios guide.
These are some of the product parameters that affect authorization behavior. Galileo sets up these and other parameters for you during program setup according to your use case, and they can also be updated later.
These parameters affect card verification.
|AAVPV||Controls whether Galileo uses the 3-D Secure validation results that it receives from a third-party access control server or a network's on-behalf services when deciding whether to approve a transaction. Set this value to |
|ATCDF||Specifies the application transaction counter (ATC) tolerance for contactless transactions. This parameter is required for contactless products. Contactless chips maintain an ATC that increments each time the card is used. For added security, Galileo keeps an independent count and compares it to the ATC. If the ATC is outside of the tolerance in this parameter, the contactless transaction is denied.|
|CVV1F||Specifies the number of failed attempts to enter CVV1 within a period before transactions are declined.|
|CVV2F||Specifies the number of failed attempts to enter CVV2 within a period before transactions are declined.|
|CVVDY||Specifies the number of days to look back when counting failed attempts to input CVV1 or CVV2.|
|NOAVS||Controls whether to disable AVS checks for authorization requests. When this parameter is set to |
|The threshold for authorization based on the network-provided risk score (DE062). Can be set for Visa, Mastercard and Pulse.|
These parameters affect PIN validation.
|EMVOP||Controls whether offline PIN functionality is enabled.|
|PBACT||Specifies which action to take after the maximum number of PIN validation failures is reached.|
|PBLOK||Specifies which types of PIN transactions are blocked: all PIN transactions, only ATM transactions, or only point-of-sale transactions.|
|PBSUC||Controls whether to reset the failed-PIN count to zero after a PIN entry is successful.|
|PBTIM||Specifies the number of hours after the last failed PIN attempt that the PIN-fail count is reset to zero. For example, if the value for this parameter is |
|FTPDY||Specifies the number of days after a PIN change that transactions are authorized for a card with offline PIN functionality.|
|FTPAM||Specifies the threshold amount for offline PIN authorization.|
These parameters affect account characteristics related to authorization.
|AAIGB||Controls whether an authorization can drive an account balance negative. When this parameter is set to |
|NOVAC||Controls whether an authorization is allowed on a cancelled account.|
|ODATM||Controls whether ATM and cash-back transactions can use overdraft.|
|PAPPR||Controls whether the account permits partial approvals for authorization requests when the request amount is larger than the available balance. When this parameter is not set, partial approvals are permitted.|
These parameters affect card loads.
|BLKLD||Specifies account statuses that block loads from load vendors.|
|DCLD||Controls whether Discover card loads are allowed.|
|MCLD||Controls whether Mastercard rePower loading is enabled.|
|VSALD||Controls whether Visa ReadyLink loading and Visa Money Transfers are allowed.|
These parameters affect balance inquiries.
|ADDOD||Controls whether to subtract the overdraft balance when returning a balance query on a reloadable card account.|
|MCBLC||Specifies which Canadian MCCs can receive the account balance in the response to a Mastercard signature or debit authorization request or balance inquiry that originates in Canada.|
|MCBLS||Specifies which MCCs can receive the account balance in the response to a Mastercard signature or debit authorization request or balance inquiry.|
|MCBLU||Specifies which United States MCCs can receive the account balance in the response to a Mastercard signature or debit authorization request or balance inquiry when the transaction originates in the United States.|
|VSBLA||Specifies whether Visa balance inquiries can receive a response. Balance inquiries can come from ATMs only.|
These parameters affect international transactions.
|BLKTM||Specifies the start and end time to block cash withdrawals in countries with country blocks.|
|CCIND||Controls which data elements determine if a transaction is foreign or domestic. When this parameter is set to |
|DOMCC||Specifies foreign countries to treat as domestic.|
|NOBLK||Specifies blocked countries where BLKTM does not apply. When a blocked country also has a block on cash withdrawals, and that country code is listed in NOBLK, then cash withdrawals are blocked in that country at all times, rather than during the times specified in BLKTM.|
These parameters affect recurring transactions.
|BLKRI||Controls whether to block recurring and installment transactions for non-reloadable prepaid Visa products. When this parameter is set to |
|BRIOD||Controls whether to block recurring transactions from using overdraft account funds.|
These parameters affect various aspects of authorization.
|CADGR||Specifies the number of days until a cash advance begins accruing interest.|
|CASHB||Controls whether a cardholder can request cash back when making a purchase.|
|ODATM||Controls whether ATM and cash-back transactions can use overdraft.|
Updated 14 days ago