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-9" target="_blank">Authorization Controller API</a> guide.

📘

Note

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

## 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 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, Visa Base II, and Interlink rails it is `VIL` or `V2L`. For authorizations the codes would be `AUA`, `DBA`, `VIA` and `V2A`, respectively.

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 are 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 the 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:rdf-reference#authorized-transactions-rdf" target="_blank">Authorized Transactions RDF</a>

📘

Note

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, below

• [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 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.

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

#### AVS check responses

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 `Y` with `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 `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 transaction 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.

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

See <a href="doc:transaction-history#obtaining-transaction-history-via-api" target="_blank">Obtaining transaction history via API</a> in the _Transaction History_ guide for the use cases for each endpoint.

## Authorized Transactions RDF

The <a href="doc:rdf-reference#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:cdf-reference#expired-auth-cdf" target="_blank">Expired Auth</a> <<CDF>>. For more information see <a href="doc:about-rdfs-and-cdfs" target="_blank">About RDFs and CDFs</a>.

## Authorization example

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 <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:

\* 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.

### PINs

These parameters affect PIN validation.

### Accounts

These parameters affect account characteristics related to authorization.

### Card loads

These parameters affect card loads.

### Balance inquiries

These parameters affect balance inquiries.

### International transactions

These parameters affect international transactions.

### Recurring transactions

These parameters affect recurring transactions.

### Miscellaneous

These parameters affect various aspects of authorization.