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 RDFRDF - Raw data file. Once per day Galileo sends you RDFs that contain a list of all of your previous day's transactions and all of your current customers. Compare the RDFs with your own records and if there are discrepancies, treat the RDFs as authoritative.s, ask for the Card Transaction Scenarios PDF from Galileo.

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 and Interlink rails it is VIL. For authorizations the codes would be AUA, DBA, and VIA, respectively.

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.

Authorization checks

When Galileo receives an authorization or a preauthorization request, it performs the following checks on the card and its account, shown in the table below. (See Validation checks in the Authorization Controller API guide for details.) The Response code column shows how Galileo responds when the check is not passed. You can see the response code that Galileo returns in the response_code field of the Authorization Events API webhooks, in the Get All Transaction History endpoint response (deny_code field, for denials only), and the AUTHORIZATION RESPONSE field of the Authorized Transactions RDF.

The actual order of the checks may vary from what is shown here.

CheckResponse codeDescription
Valid format30The message from the merchant must be properly formatted. Transactions with this error code are not present in the Authorized Transactions RDF nor are they passed through the Auth API.
Valid card number14The PAN must match a PAN that Galileo has on record and be in the proper format. If the PAN is not valid, Galileo returns code 14. Transactions with this error code are not present in the Authorized Transactions RDF nor are they passed through the Auth API.
Valid PIN55
75
If provided, the PIN that the cardholder inputs must match the hashed PIN that Galileo stores for the card. When the number of failed pin tries reaches the limit, Galileo returns code 75.
Card-security informationN7The CVV must exactly match the CVV in Galileo's system.
Expiry date54The card cannot be expired, and the expiration date provided by the merchant must match the date on record.
Card not lost41The card cannot be reported lost (status: L).
Card not stolen43The card cannot be reported stolen (status: S).
Active account and card status05Both the card and the account must be in status: N for transactions that remove funds from the account, but an account can be in other statuses to receive refunds.
Sufficient funds51Only available funds are taken into consideration. Any existing hold on the funds is subtracted from the balance to calculate the available balance.
Velocity limits61
65
Limits on the number of transactions per day or the total amount of transactions per day can be set at a product level.
Other restrictions57You can place restrictions on merchant types or locations at the product level as well as other restrictions.
Network-provided risk score59If the risk score that is provided by the card network exceeds a particular threshold, the authorization request is denied.
AVS checks85
05
If the authorization request is an AVS-only check, and the AVS check is successful, Galileo returns 85, which is an approval. If the card is not active or valid Galileo returns 05 or another appropriate code.

See the Authorization Response Codes enumeration for the full list of response codes.

If all checks are passed, Galileo sends an approval message with response code 00, or in the case of partial authorizations with code 10.

📘

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

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 such a case. 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 AVSAVS - Address verification service. An authentication method whereby the merchant submits a card's billing address in an authorization request.-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

CodeDescription
YAddress and zip code match
AOnly the address matches
ZOnly the zip code matches
NNeither address or zip code match
MGift card
UUnsupported
BAVS not used
CUnrecognized AVS return value
DNo data
RRetry AVS

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 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 transaction is not visible in the CSTCST - Customer Service Tool. Software that the Galileo customer service team uses, which is also available to providers, to view customers and their accounts. 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 AAAU: auth webhook, by request.

For more information on these checks see the Manual provisioning workflow in the About 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 AABI: bal 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 ATM withdrawal in Card Transaction Examples and these scenarios in the Card Transactions Scenarios PDF:

  • 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 preauthorization, 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 with settlement" in the Card Transaction Scenarios PDF.

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

See Obtaining transaction history via API in the Transaction History guide for the use cases for each endpoint.

Authorized Transactions RDF

The Authorized Transactions RDFRDF - Raw data file. Once per day Galileo sends you RDFs that contain a list of all of your previous day's transactions and all of your current customers. Compare the RDFs with your own records and if there are discrepancies, treat the RDFs as authoritative. contains activity in the authorization stream during a 24-hour period. 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.

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.

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.

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

ParameterDescription
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
BRSMC
BRSPU
The threshold for authorization based on the network-provided risk score (DE062). Can be set for Visa, Mastercard and Pulse.

PINs

ParameterDescription
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

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

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

Balance inquiries

ParameterDescription
ADDODControls whether to subtract the overdraft balance when returning a balance query on a reloadable card account.
MCBLCSpecifies which Canadian MCCMCC - Merchant category code. Indicates the type of merchant that acquired the payment, such as supermarket, auto supply, bakery. The codes are defined in ISO 18245.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.

International transactions

ParameterDescription
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

ParameterDescription
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

ParameterDescription
CADGRSpecifies the number of days until a cash advance begins accruing interest.
CASHBControls whether a cardholder can request cash back when making a purchase.
CBIGNSpecifies the minimum amount for chargeback disputes. The system ignores disputes below the amount in this parameter, but the ignored disputes are still visible in Galileo Analytics.
PCDAYSpecifies the number of days after the creation of a dispute to award provisional credit.

Did this page help you?