Authorization

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.

📘

Note

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. Also consult Finding Transaction Data 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 Authorized Transactions RDF 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:

See the Authorization stream 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 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.

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

• The response_code field in Authorization Events API webhooks
• Get All Transaction History endpoint response (deny_code field, for denials only)
• The AUTHORIZATION RESPONSE field in the Authorized Transactions RDF and Posted Transactions RDF

📘

Note

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.

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 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 AVS Codes 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 Amazon transaction 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 auth event webhook is sent, but the approved check 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.

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 AAAU: auth webhook, by request.

For more information on these checks see the Manual provisioning workflow 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

On an ATM, a cardholder can make a balance inquiry to display the current balance of the card account on the ATM screen. These inquiries are separate transactions from ATM withdrawals and are visible in the Authorized Transactions RDF. You can also request that the AABI: bal event be sent for these transactions. The otype for a balance inquiry at an ATM is B (or 10 in the Authorized Transactions RDF) and the amount is usually 0.00, though in some countries, there is a fee in the amount field.

Merchants can also request a balance return with a conventional authorization request for a purchase. These requests are not separate transactions, and so the AABI: bal event is not triggered. See Balance inquiry responses in the Authorization Controller API guide for more information on the difference between a balance inquiry and a balance return.

For examples see ATM withdrawal in Card Transaction Examples and these other scenarios:

• Scenario 11: ATM Withdrawal
• Scenario 12: ATM Reversal

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

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 BAUT: auth webhook that contains the auth_id of the previous authorization in the sequence in the original_auth_id field.

For examples see the Incremental authorization example in Card Transactions Examples and Scenario 3: Incremental Authorizations

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

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:

• Get Authorization History — Returns only unsettled, uncompleted, and unexpired authorizations
• Get Account Overview — Returns unsettled, uncompleted, and unexpired authorizations in the authorizations object of the response.
• Get All Transaction History — Returns all transactions: settled, unsettled, unexpired, uncompleted, and completed as well as backouts

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 RDF. For more information see About the Raw Data Files (RDFs).

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

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

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.