This guide explains authorization in depth. Before reading this guide you should be familiar with the concepts in these guides:

  • <a href="doc:about-transactions" target="_blank">**About Transactions**</a> — A general guide to how transactions are represented in the Galileo system.

  • <a href="doc:about-card-transactions" target="_blank">**About Card Transactions**</a> — 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 <a href="doc:authorization-controller-api" target="_blank">Authorization Controller API</a> guide.


To see detailed examples of transaction sequences as they appear in the Program API, Events API, Auth API, and <<glossary:RDF>>s, consult the <a href="page:card-transaction-scenarios-index" target="_blank">Card Transaction Scenarios</a>. Also consult <a href="page:finding-transaction-data" target="_blank">Finding Transaction Data</a> to see where transaction types are visible.

## 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.

### Identifying preauthorizations

Galileo identifies preauthorizations based on information in the authorization request, and each network uses a different method to identify a preauthorization. Preauthorizations are differentiated from authorizations in the <a href="doc:base-rdfs#authorized-transactions-rdf" target="_blank">Authorized Transactions RDF</a> by the `AUTH TRANSACTION CODE` field. A preauthorization is otype `L` and authorizations are otype `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 `AUA`, `DBA`, and `VIA`, respectively.

You can see the transaction codes and otypes that differentiate authorizations and preauthorizations in these places:

Event webhooks`otype`
Authorized and Posted Transactions RDFs`AUTH TRANSACTION CODE`
Get Authorization History and Get All Transaction History`type`
Get Account Overview`trans_code`

See the <a href="ref:api-reference-transaction-types#authorization-stream" target="_blank">Authorization stream</a> table in 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 <a href="doc:settlement#completion" target="_blank">Completion</a> 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 <a href="doc:settlement" target="_blank">Settlement</a> guide for more information.

## Authorization checks

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 is in the <a href="ref:api-reference-events-authorization-response-codes" target="_blank">Authorization Response Codes</a> enumeration. Also consult the <a href="doc:authorization-controller-api#validation-checks" target="_blank">Auth API Validation Checks</a> guide for a detailed description of the checks.

You can see the response code that Galileo returns in these places:

  • The `response_code` field in <a href="ref:authorization-events-webhook" target="_blank">Authorization Events API</a> webhooks

  • <a href="ref:post_getalltranshistory" target="_blank">Get All Transaction History</a> endpoint response (`deny_code` field, for denials only)

  • The `AUTHORIZATION RESPONSE` field in the <a href="doc:base-rdfs#authorized-transactions-rdf" target="_blank">Authorized Transactions RDF</a> and <a href="doc:base-rdfs#posted-transactions-rdf" target="_blank">Posted Transactions RDF</a>


You can be involved in the authorization process by using the <a href="ref:api-reference-auth-api-about-auth-api" target="_blank">Authorization Controller API</a> (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.

## Authorization variants

Besides authorizations and preauthorizations, you will encounter these variants on authorizations:

  • [Upcharges](🔗)

  • [Partial authorizations](🔗)

  • [AVS-only checks](🔗)

  • [Bulk authorization](🔗)

  • [Provisioning requests](🔗)

  • [ATMs](🔗)

  • [Balance inquiries](🔗)

### Upcharges

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 a card program can decide to preauthorize only the requested amount plus a fixed percentage as an _upcharge_, or the upcharge can be a fixed amount. 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.

### Partial authorizations

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 `10`.

### AVS-only checks

Online merchants, both on web sites and in phone apps, often perform an <<glossary: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.

See <a href="ref:api-reference-avs-codes" target="_blank">AVS Codes</a> for the list.

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 not taken into consideration when calculating 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 could decide to continue with the sale. It is also possible for Galileo to return a `Y` with `05`, meaning that the address information matched but the transaction is denied for another reason.

See the <a href="doc:card-transaction-examples#amazon-transaction" target="_blank">Amazon transaction</a> in _Card Transaction Examples_ for more information.

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 `85` or `00`, the transaction is visible in the Authorized Transactions RDF and an <a href="ref:api-reference-events-api-auth" target="_blank">`auth`</a> event webhook is sent, but the approved check is not visible in the <<glossary: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.

#### ANI support

For Mastercard and Visa, Galileo supports Account Name Inquiry (ANI), which is a name-matching check that a merchant or real-time payment originator can request along with an AVS check. Galileo compares the first, middle, and last names provided in the request to the names on file. Galileo's response indicates whether there's a full match, partial match, or no match. The ANI results are visible to the merchant or payment originator but are not returned in the RDFs or event messages.

### Bulk authorization

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.

### Provisioning requests

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 <a href="ref:api-reference-events-api-auth" target="_blank">`AAAU: auth`</a> webhook, by request.

For more information on these checks see the <a href="doc:setup-for-mobile-wallets#manual-provisioning-workflow" target="_blank">Manual provisioning workflow</a> in the _Setup for Mobile Wallets_ guide.

### ATMs

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 `SDW`.

#### Balance inquiries

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 <a href="ref:api-reference-events-api-bal" target="_blank">`AABI: bal`</a> event be sent. The transaction type for a balance inquiry at an ATM is `B` (or `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 <a href="doc:card-transaction-examples#atm-withdrawal" target="_blank">ATM withdrawal</a> in _Card Transaction Examples_ and these other scenarios:

  • <a href="page:scenario-11-atm-withdrawal" target="_blank">Scenario 11: ATM Withdrawal</a>

  • <a href="page:scenario-12-atm-reversal" target="_blank">Scenario 12: ATM Reversal</a>

## Authorization linkage

Some authorization requests need to reference a previous authorization. The previous authorization is linked to the current authorization by a linking identifier. See <a href="doc:about-transactions#linking-transactions" target="_blank">Linking transactions</a> 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 <a href="doc:crediting-cardholder-accounts#reversals" target="_blank">Reversals</a> 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 <a href="doc:settlement#completion" target="_blank">Completion</a> 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.

## Incremental authorizations

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 <a href="ref:api-reference-events-api-auth" target="_blank">`BAUT: auth`</a> webhook that contains the `auth_id` of the previous authorization in the sequence in the `original_auth_id` field.

For examples see the <a href="doc:card-transaction-examples#incremental-authorization" target="_blank">Incremental authorization</a> example in _Card Transactions Examples_ and <a href="page:scenario-3-incremental-authorizations" target="_blank">Scenario 3: Incremental Authorizations</a>

## Authorization expiry

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 <a href="doc:settlement" target="_blank">Settlement</a> 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 <a href="ref:api-reference-events-api-auth-exp" target="_blank">`BEXP: auth_exp`</a> 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 <a href="ref:api-reference-events-api-setl" target="_blank">`SETL: setl`</a> webhook.

When an authorization is reversed before clearing, both the authorization and reversal are pending until the expiry time elapses. See <a href="doc:crediting-cardholder-accounts#reversals" target="_blank">Reversals</a> in the _Crediting Cardholder Accounts_ guide for more information.

## International merchants

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:

  • <a href="ref:post_getauthhistory" target="_blank">**Get Authorization History**</a> — Returns only unsettled, uncompleted, and unexpired authorizations

  • <a href="ref:post_getaccountoverview" target="_blank">**Get Account Overview**</a> — Returns unsettled, uncompleted, and unexpired authorizations in the `authorizations` object of the response.

  • <a href="ref:post_getalltranshistory" target="_blank">**Get All Transaction History**</a> — Returns all transactions: settled, unsettled, unexpired, uncompleted, and completed as well as backouts

## Authorized Transactions RDF

The <a href="doc:base-rdfs#authorized-transactions-rdf" target="_blank">Authorized Transactions</a> <<glossary:RDF>> contains activity in the authorization stream during a 24-hour period. You can also request that Galileo send you the <a href="doc:service-rdfs#expired-auth-rdf" target="_blank">Expired Auth</a> RDF. For more information see <a href="doc:about-the-raw-data-files-rdf" target="_blank">About the Raw Data Files (RDFs)</a>.

## Authorization example

To see an authorization in a Program API response and an explanation of the fields, open this Recipe:

Get Authorization History response
Open Recipe

## Authorization Events messages

Authorization-related webhooks are sent to the <a href="ref:authorization-events-webhook" target="_blank">Authorization Events</a> endpoint. Consult the <a href="ref:api-reference-events-api-authorization-events-index" target="_blank">Authorization Events Index</a> for the list and <a href="doc:about-the-events-api" target="_blank">About the Events API</a> for general information.

There are two types of <a href="ref:api-reference-events-api-auth" target="_blank">`auth`</a> event, known by the codes `BAUT` and `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 (`msg_id`).

`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

To differentiate among different AAAU messages, consult this table:

AAAU typeIndicators
CompletionThe `original_auth_id` field is populated, and the `amount` is a negative number.
ReversalThe `amount` is the opposite sign of the transaction in the `original_auth_id` field.
AVS-only requestThe `amount` is 0.00 and `card_not_present: Y`\*.
Tokenization request, yellow pathThe `token_type` field is populated and `response_code: 85`.

\* Field enabled by request.

`BAUT` is sent for all other authorization requests except these

  • <a href="ref:api-reference-events-api-bal" target="_blank">`AABI: bal`</a> — Balance inquiries. This event is sent to the Account Events endpoint because it does not affect the available balance.

  • <a href="ref:api-reference-events-api-auth-payment" target="_blank">`AAPM: auth_payment`</a> — Card loads

To see examples of transaction sequences with Events API webhooks, see <a href="doc:events-api-scenarios#authorization-events" target="_blank">Authorization events</a> in the _Events API Scenarios_ guide.

## Galileo setup

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.

### Card verification

These parameters affect card verification.

AAVPVControls 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 `Y` for Galileo to use the validation results. When this parameter is not set, Galileo does not use the validation results for decisioning.
ATCDFSpecifies 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.
CVV1FSpecifies the number of failed attempts to enter CVV1 within a period before transactions are declined.
CVV2FSpecifies the number of failed attempts to enter CVV2 within a period before transactions are declined.
CVVDYSpecifies the number of days to look back when counting failed attempts to input CVV1 or CVV2.
NOAVSControls whether to disable AVS checks for authorization requests. When this parameter is set to `1`, an AVS check is not performed but instead a "gift" response is returned, which the merchant can interpret as success or failure and then act on according to merchant policy. Do not set this parameter for products that support Apple Pay — it causes tokenization to fail.
BRSGE<br>BRSMC<br>BRSPUThe threshold for authorization based on the network-provided risk score (DE062). Can be set for Visa, Mastercard and Pulse.

### PINs

These parameters affect PIN validation.

EMVOPControls whether offline PIN functionality is enabled.
PBACTSpecifies which action to take after the maximum number of PIN validation failures is reached.
PBLOKSpecifies which types of PIN transactions are blocked: all PIN transactions, only ATM transactions, or only point-of-sale transactions.
PBSUCControls whether to reset the failed-PIN count to zero after a PIN entry is successful.
PBTIMSpecifies 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 `3`, then the PIN-fail counter is reset to zero three hours after the last failed PIN attempt.
FTPDYSpecifies the number of days after a PIN change that transactions are authorized for a card with offline PIN functionality.
FTPAMSpecifies the threshold amount for offline PIN authorization.

### Accounts

These parameters affect account characteristics related to authorization.

AAIGBControls whether an authorization can drive an account balance negative. When this parameter is set to `Y`, response codes `00` and `10` are allowed to drive a balance negative. When this parameter is not set, all authorization requests that result in a negative balance are declined.
NOVACControls whether an authorization is allowed on a cancelled account.
ODATMControls whether ATM and cash-back transactions can use overdraft.
PAPPRControls 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.

### Card loads

These parameters affect card loads.

BLKLDSpecifies account statuses that block loads from load vendors.
DCLDControls whether Discover card loads are allowed.
MCLDControls whether Mastercard rePower loading is enabled.
VSALDControls whether Visa ReadyLink loading and Visa Money Transfers are allowed.
STRLDControls whether STAR loads are allowed.

### Balance inquiries

These parameters affect balance inquiries.

ADDODControls whether to subtract the overdraft balance when returning a balance query on a reloadable card account.
MCBLCSpecifies which Canadian <<glossary:MCC>>s can receive the account balance in the response to a Mastercard signature or debit authorization request or balance inquiry that originates in Canada.
MCBLSSpecifies which MCCs can receive the account balance in the response to a Mastercard signature or debit authorization request or balance inquiry.
MCBLUSpecifies 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.
VSBLASpecifies whether Visa balance inquiries can receive a response. Balance inquiries can come from ATMs only.

### International transactions

These parameters affect international transactions.

BLKTMSpecifies the start and end time to block cash withdrawals in countries with country blocks.
CCINDControls which data elements determine if a transaction is foreign or domestic. When this parameter is set to `Y`, the determining fields depend on the card network.
DOMCCSpecifies foreign countries to treat as domestic.
NOBLKSpecifies 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.

### Recurring transactions

These parameters affect recurring transactions.

BLKRIControls whether to block recurring and installment transactions for non-reloadable prepaid Visa products. When this parameter is set to `Y`, recurring and installment transactions are blocked for non-reloadable prepaid Visa products.
BRIODControls whether to block recurring transactions from using overdraft account funds.

### Miscellaneous

These parameters affect various aspects of authorization.

CADGRSpecifies the number of days until a cash advance begins accruing interest.
CASHBControls whether a cardholder can request cash back when making a purchase.
ODATMControls whether ATM and cash-back transactions can use overdraft.