Authorization Controller API

With the Authorization Controller API (Auth API) Galileo clients have the ability to participate in the approval process for authorization requests that arrive over card-network rails. This guide explains how to use the Auth API and how to interpret the webhook.

You can view the full reference guide for the Auth API webhook fields here:

This guide assumes that you are familiar with the concepts explained in these guides:

To see how specific transaction types are represented in the Events API, Program API and RDF data alongside Auth API data,see the Card Transactions Scenarios. For actual Auth API webhooks, see Auth API v3 webhook examples on this page.

Differences between version 2 and version 3

All new clients are set up on version 3. For clients on version 2 who want to upgrade to version 3, these are the differences between the versions of the Auth API:

  • Version 3 includes this field:
    • response_code_objects — An object that contains a list of response codes and textual descriptions that Galileo calculated when determining the value in response_code.
  • Version 3 does not include this field:
    • response_code_list — A list of response codes that Galileo calculated when determining the value in response_code.



Version 3 is a breaking change from version 2.


The specifics of your setup will be particular to your use case and to the types of systems you are using. Whatever you construct to handle the Auth API, your endpoint must be able to handle what Galileo sends:

  • Authentication uses a JWT with a shared secret. See Security in the Auth API reference for details.
  • The webhook payload is sent as an HTTP POST using HTTP/1.1 over TLS.
  • You must respond within 2 seconds of the value in the webhook's timestamp field, which is when Galileo sent the webhook.
  • Galileo initiates multiple, simultaneous TCP sessions and sends webhooks in parallel on those connections.
  • For efficiency, Galileo uses the keep-alive function instead of terminating each connection.
  • How many connections per second depends on how many cardholders you have and how often they perform card transactions. You must use your own business logic to obtain this sizing information.

Decisions to make

When designing your implementation of the Auth API, you will need to address issues such as these, as well as others:

  • Whether you or Galileo will be the system of record. This decision affects funds flow, how parameters are set on the back end, how you respond to the webhooks, and other considerations.
  • How to respond to balance inquiries.
  • When to override the Galileo response code, if permitted.
  • Whether to implement a real-time funding strategy to transfer funds into a cardholder account to cover the amount of an authorization.
  • How to deal with edge cases. Consult the Card Transactions Scenarios for detailed examples of some of the transaction types you will encounter:
    • Completions and settlements
    • Incremental authorizations
    • Reversals and their expiry
    • Advices

Message workflow

This is the general sequence of events for an authorization:

  1. The merchant sends an authorization request to its acquirer.
  2. The acquirer forwards the request to the network.
  3. The network forwards the request to Galileo.
  4. Gaileo forwards the request to you.
  5. You return a response to Galileo.
  6. Galileo forwards the response to the network.
  7. The network forwards the response to the acquirer.
  8. The acquirer forwards the response to the merchant, who completes the transaction.

Message types

Messages sent between acquirers and issuers over card-network rails conform to the ISO 8583 standard. The standard defines message type indicators (MTIs), which specify the type of message being sent and indicate what kind of response is expected. MTIs are four-digit codes that are broken out as follows, with the values that are most likely to be included with Auth API webhooks:

  • First digit — Version of ISO 8583 used
    • 0 — 1987 version
    • 1 — 1993 version
  • Second digit — General purpose of the message
    • 1 — Authorization message
    • 2 — Financial message
    • 4 — Reversals and chargebacks
  • Third digit — Message function
    • 0 — Request
    • 1 — Request response
    • 2 — Advice
    • 3 — Advice response
  • Fourth digit — Session initiator
    • 0 — Acquirer
    • 2 — Issuer

The typical flow of messages between acquirer and issuer follows this pattern:

  1. The merchant sends a message to its acquirer.
  2. The acquirer converts the message into ISO 8583 format and sends the message to the card network with a request or notification-type MTI.
  3. The network forwards the message to the issuer.
  4. The issuer processes the message information and then sends a response message to the network with a response-type MTI.
  5. The network forwards the response to the acquirer.
  6. The acquirer processes the message and sends the response to the merchant.

For example, when an acquirer sends an authorization request over credit rails, the MTI is 0100, and when the issuer responds it's MTI 0110.

These are the most common MTI request/response combinations that you will encounter with the Auth API.

DescriptionFrom acquirerIssuer response
Authorization or preauthorization request over credit rails or preauthorization request over debit rails01000110
Authorization request over debit rails02000210
Advice over credit rails01200130
Advice over debit rails02200230
Authorization reversal over credit or debit rails04200430

When you send your response to Galileo, you are not required to provide the MTI: Galileo will convert your response into ISO 8583 format and include the appropriate MTI to send to the network.



When the third digit is 2, the message is an advice, which you cannot reject: only a 00 response code is permitted.

Alongside the MTI in the webhook, Galileo further breaks down message types based on other information that it receives in the message to provide you with more detail. This information is provided in the auth_type and transaction_type fields. These are the combinations you will most likely encounter.

Authorization requestAuthAuth0100 (credit rails)
0200 (debit rails)
Preauthorization requestAuthPreauth0100
ATM withdrawal requestAuthATM0200
Request for a cash advance from a tellerAuthCash Advance0200
Balance inquiry from an ATM or other vendorAuthBalance Inquiry0200
Request to apply credit from a merchantAuthMerchant Credit0200
Request to load a cardAuthPayment0200
Request to convert a card into a token for a mobile walletAuthTokenization0100
Notification of a completionAdviceAuth0120 (credit rails)
0220 (debit rails)
Notification of a reversalReversalAuth0420

Data elements

The ISO 8583 standard defines data elements (DEs) that contain details about the transaction, such as transaction amounts, card-reader identifier and PIN capabilities, merchant name and identifier, and currency codes and conversion rates. Galileo extracts information from the DEs and converts it into the human-readable field names and values of the Auth API webhook. Because each network uses the DEs differently, the documentation does not always indicate which DE corresponds to which Auth API field. Refer to the documentation from each network to see how they use the DEs.

Auth API process

This is the sequence of events between Galileo and you for a typical authorization request.

  1. Galileo receives an authorization request over a card network's rails in ISO 8583 format.
  2. Galileo performs validation checks and calculates response codes.
  3. Galileo converts its response codes and selected elements of the network message into webhook format and sends it to you.
  4. You apply logic to decide whether to override Galileo's response code, if permitted.
  5. You send your response to Galileo within two seconds.
  6. Galileo converts your response into ISO 8583 format and forwards it to the network.

Validation checks

Galileo performs these checks on all incoming authorization requests. The actual order of the checks may vary from what is shown here.

Consult the Authorization Response Codes enumeration to see codes that Galileo supports. You may also arrange with Galileo to send custom response codes, depending on your use case and business requirements.

PAN validation

The PAN must exist in the Galileo system. If the PAN does not exist, Galileo returns 14 (invalid card number) to the network and performs no further checks. When Galileo returns a 14, you do not receive a webhook.

Card validation

The card-validation checks help ensure that the card used at the point of sale is an authentic card and that an authorized cardholder is presenting it. The summary of card-validation results is in the validation_results object.

AVS check

See AVS-only checks in the Authorization guide for an explanation of these checks.

Galileo returns the result of an AVS check in the avs_result field. In the avs_data object, Galileo provides the information that it used to perform the check. If you have reason to believe that Galileo is not using the correct address for the account, you can perform AVS yourself and override Galileo's result. See AVS override for more information.

Galileo does not use AVS results to calculate a response code: Merchants decide how to handle each result. It is therefore possible for Galileo to return avs_result: N with response_code: 00, which means that there was no AVS match but the transaction is otherwise approved, because the account supports it.

If you do not want AVS checks for your product, such as for gift cards, set the NOAVS product parameter to return a "gift" value for avs_result. Merchants can decide whether to accept the result as success or failure and then proceed according to their business policies.


When a PIN is not provided, the transaction usually arrives at Galileo over credit rails and pin: N.

When a PIN is provided, the transaction usually arrives at Galileo over debit rails. These are the steps for validating the PIN. The actual order of the steps may vary from what is shown here:

  1. Galileo checks whether a PIN has been set for the card. If it has not been set, Galileo returns 55 (incorrect PIN) and pin: M.
  2. If a PIN has been set, Galileo checks whether PBLOK permits this type of PIN transaction. If it does not, Galileo returns 57 (transaction not permitted to cardholder) and pin: B (blocked).
  3. If this type of PIN transaction is permitted, Galileo checks whether the PIN has been locked after exceeding the number of failed PIN attempts. If it has, Galileo returns 75 (allowable number of PIN tries exceeded) and pin: L (locked). (The failed PIN count will reset to zero after the time specified in PBTIM.)
  4. If the PIN has not been locked, Galileo compares the provided PIN to the hashed PIN that Galileo has on record. If the PINs do not match, Galileo returns 55 (incorrect PIN) and pin: F.
  5. If all checks are passed, the pin field contains Y (verified).
Offline PIN

Some implementations of EMV chips permit card readers to validate PINs without contacting the issuer. With offline PIN validation, the chip contains a PIN block (encrypted PIN) that the card reader compares to the PIN provided on the keypad. The card reader includes the result in the authorization request message.

Galileo passes the summary of the result in the offline_pin field. This table shows which other fields will be populated according to the result.

offline_pinMeaningOther fields
YValidatedcardholder_verification_not_successful: false
FFailedcardholder_verification_not_successful: true
NNot presentis_emv: false
emv object not populated
EOffline PIN attempts exceededpin_try_limit_exceeded: true
PIgnored, because the transaction amount is less than a specified thresholdNone

The terminal_verification_results (TMV) object inside the emv object contains the results of the PIN verification. The raw field contains a value provided by the network, and the meaning of the value is different for each network. Galileo provides the interpretation of the raw field in the rest of the fields inside the TMV object.

In most cases, the card reader can verify the PIN using the chip, but if the PIN has been recently changed, the reader needs to contact the issuer for verification. When the card reader is requesting online PIN verification from Galileo, then online_pin_entered: true.

See Offline PINs in the PIN-Set Procedures guide for more information on changing offline PINs.


Galileo checks whether the CVV matches the hashed CVV in the Galileo system. There are three possible CVV values to match, depending on how the card information was acquired:

  • CVV1 — Embedded in tracks 1 and 2 of a magnetic stripe, it verifies that merchants have the physical card in their possession for card-present transactions. When this CVV does not match, Galileo returns 05 (do not honor).
  • CVV2 — Printed on a card, this three-digit number is used for card-not-present transactions. When this CVV does not match, Galileo returns N7 (CVV2 error) for Visa or 05 (do not honor) for Mastercard.
  • CVV3 — This code is cryptographically generated by a contactless transaction and verified by the issuer. When this CVV does not match, Galileo returns 05 (do not honor) and arqc: F.

3-D Secure

Some e-commerce sites add another layer of cardholder verification using the 3-D Secure protocol (3DS), which is a two-step authentication process that cardholders must pass at the time they attempt to make a purchase on a 3DS-enabled web site. The standard in general is facilitated by EMVco, and each card network has a branded implementation of 3DS:

  • Visa — Visa Secure
  • Mastercard — SecureCode
  • Discover — ProtectBuy

Galileo recommends that you obtain documentation from the networks to better understand how they implement 3DS.

This table shows country-by-country requirements for 3DS as of October 2021.

Countries with regulation requiring a service like 3DSCountries that strongly recommend having 3DSNo current requirements for 3DS
All European countries
South Africa
United States

For 3DS to be successful, three entities must be participating in 3DS:

  • The merchant
  • The issuer
  • The cardholder

When a cardholder attempts to make a purchase on a 3DS-enabled site, the results of the authentication are passed in the authorization request, and Galileo includes them in the aav field and the ecommerce object. When the e-commerce site does not implement 3DS, is_ecommerce: false and the remaining fields in the ecommerce object are not sent.

Galileo does not currently perform 3DS validation. You may integrate with a third-party 3DS provider, called an access control server (ACS), if you want to support 3DS, or you may use the networks' on-behalf services. The 3DS-related fields that Galileo relays in the Auth API webhook show the results of 3DS validation after it has been performed by the ACS or network. Galileo approves or denies transactions based on the validation results, and so these fields are provided for your information, not for decisioning.

As you parse the ecommerce object, remember that some combinations of values result in a liability shift from the merchant to the issuer. Consult the documentation from each network to see which results trigger a liability shift.

The AAVPV product parameter controls whether Galileo uses the validation results that it receives from the ACS or network 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 3DS validation results for decisioning.

See the reference material for the Auth API v2 or Auth API v3 for details on what each e-commerce field means.

Transaction type validation

Galileo checks product and account settings to determine whether the transaction type is permitted to the cardholder. When any of the following items is true, Galileo returns 57:

  • ATM withdrawals are blocked by account feature 9 or PBLOK.
  • Point-of-sale (POS) transactions are blocked by PBLOK.
  • Recurring transactions are blocked by BLKRI.
  • Non-mobile-wallet transactions are blocked by account feature 20.
  • Card-present transactions (except mobile wallet) are blocked by account feature 21.
  • Mobile wallet transactions are blocked by account feature 22.
  • Card-not-present transactions are blocked by account feature 6.
  • Cash transactions are blocked by product settings.
  • Cashback transactions are blocked by CASHB.
  • Cash advances are blocked by account feature 10.
  • Cash and POS transactions are blocked in this country.
  • International transactions are blocked by account feature 8.
  • Transactions with this MCC are blocked.
  • Card loads are not allowed by product settings.
  • Suspected fraud (all but Visa and STAR).

Where there is an account feature blocking the transaction, you can call Set Account Feature to unblock the transaction type for that account. Where a product parameter or product settings block the transaction, you can ask Galileo to change the setting for the product.

Account validation

Galileo verifies that the account can support the transaction.

Card and account status

Galileo verifies that the card and account statuses are both N (normal, active). For Visa cards, if the card or account is in any status except N—including lost or stolen—Galileo returns 46 (closed account).

For all other networks, if the card status is S (stolen), Galileo returns 43 (stolen card, pick up), or if the card status is L (lost), Galileo returns 41 (lost card). For any other account statuses besides N, S, or L, Galileo returns 05 (do not honor).

Card frozen

The "frozen" attribute of a card is independent of its status. An authorization request for a frozen card is always denied. Galileo returns 78 (card frozen) for Visa or 57 (transaction not permitted) for all other networks.

Expiry date

For card-not-present transactions, the expiry date that the cardholder entered is in merchant_supplied_expiration_date. For card-present transactions the expiry data in the magnetic stripe is in track_expiration_date.

Galileo checks the expiry date against the expiry date in the Galileo system to ensure that the values match. Galileo provides the date that it has on file in expiration_date. If the dates do not match, Galileo returns 54 (card expiration date mismatch). If the expiration date has passed, Galileo also returns 54.

Sufficient funds

If Galileo holds the account balance, Galileo checks the available funds in the cardholder account against the amount in trans_amount. The available funds do not include any holds, such as from previous unsettled authorizations. Galileo populates the available funds in the available_funds field in the amounts object. This value represents the account balance before the transaction is applied.

If you hold the account balance, you must determine whether the account can support the amount in trans_amount, based on your records.

If the account does not contain sufficient funds, the standard response code is 51 (insufficient funds). However, there are several ways to address insufficient funds without returning 51:

  • Partial authorization — If the merchant accepts partial authorizations (partial_supported: true), you or Galileo can return the amount of the authorization in partial_amount with response code 10.
  • Overdraft — If you have set up overdraft, your account settings determine whether an ATM withdrawal can use overdraft (ODATM) and also whether the overdraft funds are moved at the time of authorization or settlement (ODTOR).
  • Real-time transfers — You move funds from a dedicated account into the cardholder account to cover the authorization amounts.

Velocity limits

Galileo checks whether the transaction violates velocity limits—whether the amount or number of transactions exceeds a threshold, for example. These velocity limits are determined at the time you set up your products. You can also arrange with Galileo to create account-level velocity controls (ALCs). (See About Account-Level Authorization Controls for more information.)

If trans_amount violates an amount limit, Galileo returns 61 (exceeds withdrawal amount limit) or if a transaction-count limit is reached Galileo returns 65 (exceeds withdrawal frequency limit).

Also see Overriding limits.

Other checks

These other checks validate characteristics of the transaction not included in the previous categories.

Merchant validity

According to your product settings you can prohibit transactions with certain merchant types (per MCC) or by merchant ID. For ATM withdrawals in specified countries you can prohibit transactions at certain times of day. You can also arrange with Galileo to create account-level merchant controls (ALCs). (See About Account-Level Authorization Controls for more information.)

If the MCC or merchant ID is prohibited, Galileo returns 57 (transaction not permitted to cardholder).


Galileo verifies that the transaction is taking place in a country that has not been blocked in your product settings. If the country has been blocked, Galileo returns 62 (card not valid in this region) for Visa or 05 (do not honor) for all other networks.

Fraud risk

Galileo compares the value that the network provides in risk_score with the value set in product parameters (BRSGE, BRSMC or BRSPU). If the risk score exceeds the threshold, Galileo returns 59 (suspected fraud) for Visa and STAR networks or 57 for the others. Risk scores are not returned when the transaction is an advice, because the transaction has already been acted on by the network.

If you are using Galileo's dynamic fraud rules engine, any rule violations are reported in the rules_denied and rules_warned fields, provided you have the RULAP product parameter set. When the rule violations are sufficient to deny a transaction, Galileo returns 59.

See Authorization checks in the Authorization guide for a summary of response codes for failed validation checks.

Tokenization requests

Networks send tokenization requests when the card is first provisioned to a mobile wallet, either with manual provisioning or push-provisioning. (See Setup for Mobile Wallets for the Galileo provisioning procedures.) A tokenization request for an initial provisioning has the name of the wallet provider for token_type.

Merchants also send tokenization requests to perform AVS checks on tokenized cards before accepting the cards as payment in an app or on a website. In this case, token_type: Merchant.

The network relays provisioning requests that it receives from wallet providers and merchants. The requests are MTI 0100 and contain the PAN and cardholder identifiers.

  • If the card was push-provisioned through your app or web site, the cardholder's identity and card information have already been verified. Galileo responds with 00.
  • If the card was manually provisioned, the wallet provider is requesting additional verification checks such as AVS, CVV2, and the last four digits of the cardholder's phone number. Galileo responds with the AVS result plus 05, 85, or 00, depending on which checks were passed. For initial provisioning requests, see the Manual provisioning workflow in the Setup for Mobile Wallets guide for details.
  • For merchant AVS requests, Galileo responds to a successful check with code 85 (AVS requested to verify account) or with 05 (do not honor) to an unsuccessful check.
  • Additional tokenization data may be present in the tar_object, which contains details about the tokenization authorization request (TAR) such as risk scores, device location, device ID and a recommendation from the wallet provider that indicates whether the tokenization request should be approved.

When the network notifies Galileo whether the provisioning request was successful, Galileo sends you an Account Event API webhook that corresponds to the result, such as ATCN: mobile_activation TCN for a successful provisioning to an Apple Pay wallet. See Events API messages in the Setup for Mobile Wallets guide for a list of tokenization-related event messages.

IIAS fields

Clients who issue Visa FSA (flexible spending account), HRA (health reimbursement arrangement) or HSA (health savings account) cards can receive data in the iias_data object that indicates whether the item or service being purchased is an eligible medical expense. An inventory information approval system (IIAS) at the point of sale provides this verification. Where merchants sell both qualified and non-qualified goods and services, the qualified_healthcare_products_total field indicates how much of a purchase is a qualified medical purchase.



Some medical merchants do not use IIAS because their card readers are programmed with a healthcare-related MCC such as 8099 (Medical Services and Health Practitioners). FHA/HRA/HSA cards can be used at these locations without IIAS verification.

Advanced Auth API fields

The advanced_auth_api_fields object is provided only to those clients who request that additional data elements (DEs) be parsed and returned in the Auth API webhook. The ADVAF parameter must be set for these fields to be returned, and the network must be Mastercard.

Point of sale data

DE061 contains information about the conditions that exist at the point of sale (POS) at the time of the transaction. Consult the DE061 Subfields enumeration for a list of included subfields and their values.


"advanced_auth_api_fields": {
    "61": {
        "subfield 8": "0",
        "subfield 1": "1",
        "subfield 3": "2",
        "subfield 4": "5",
        "subfield 5": "1",
        "subfield 6": "0",
        "subfield 12": "00",
        "subfield 10": "6"

Subscription services

If you subscribe to Mastercard services such as Fraud Rule Management (FRM) or Safety Net, these services may make decisions on transactions before they are forwarded to Galileo. If one of the services declines a transaction, it sends an advice (MTI 0120) to Galileo to notify of the decline.

Galileo can pass data elements in the Auth API webhook that provide information on the decline. Sample values are shown below—consult the documentation from Mastercard to interpret the values you receive. Values for all of these fields may or may not be returned depending on which services you're subscribed to.

For example, if the transaction is declined by Safety Net, these are the values passed in the webhook:

  • DE048 — Additional information
    • Subfield 71 — On-behalf service (OBS)
      • Subelement 118 (fraud scoring service)
      • Subelement 2C (fraud scoring service successful)
    • Subfield 75 — Fraud assessment prediction information
      • Subelement 1998 or 000
      • Subelement 2NM (network monitor)
      • Subelements 3–5 — Rule-adjusted score and reason code
  • DE060
    • Subfield 1 (Advice reason code) — 120 (transaction blocking)
  • DE121 (Authorizing agent identification code) — 000003 (decline from on-behalf service)


"advanced_auth_api_fields": {
    "48": {
        "subfield 71": "18C",
        "subfield 75": "998NM500202110303850040211050200"
    "60": {
        "subfield 1": "120"
    "121": "000003"

Calculating a response code

Based on the checks Galileo performs, Galileo populates response_code_list (version 2) or response_code_objects (version 3). From these lists, Galileo selects the response code to return in the response_code field. Galileo chooses the response_code from among multiple codes according to a proprietary algorithm.

Galileo returns 00 (success) if no other response codes were generated or if the authorization message is an advice. When the response code is 00, response_code_objects or response_code_list is empty.

Sending a response

Your response must be in JSON format. Sample responses are in the reference (Version 2, Version 3). The response must arrive at Galileo within two seconds of the time Galileo sent the webhook to you. If you do not respond in time, Galileo may perform fallback processing, depending on your arrangements with Galileo. See Fallback processing for more information.


You are permitted to override Galileo's responses only under certain circumstances.

Response code override

Galileo recommends that you build logic to override these response codes only:

  • 00 — Success
  • 10 — Approved for partial amount
  • 51 — Insufficient funds
  • 59 — Suspected fraud

Overriding these response codes requires bank approval. To add more response codes to override after initial setup, you will need additional bank approval and a legal addendum to the Master Service Agreement.

AVS override

When Galileo performs AVS checks, the verdict is in the avs_result field and the values used to perform the check are in the avs_data object. If you have reason to believe that Galileo does not have the latest address information, you can perform AVS yourself on the updated address and populate avs_response to override Galileo's result.

Overriding insufficient funds

When Galileo returns 51 (insufficient funds), you can override it in one of two ways: partial authorization or real-time transfers. Alternatively, Galileo can provide partial authorizations.

Partial authorization

Merchants determine whether they will accept partial authorizations. If the merchant accepts partial authorization, then partial_supported: true.

If you hold the balance, populate partial_amount with the amount to authorize for the transaction and return response_code: 10 (approved for partial amount) or response_code: 87 (approved for partial purchase amount but not cash back).

If Galileo holds the balance, the partial_amount field is already populated with the amount to authorize—which will be the available balance—and response_code: 10. If you do not want to authorize the partial amount, return response_code: 51 to override Galileo's code.

If you never want to support partial authorizations, set the PAPPR parameter.

Real-time transfers

As desired, you can build logic on your side to transfer funds into a cardholder account to cover the amount of an authorization when the cardholder account has insufficient funds. In that case, you populate these fields:

  • transfer_prn — The PRN of the account to provide funds.
  • transfer_amount — The amount of the transfer.
  • source_transfer_type — Transaction type code for the account in transfer_prn.
  • dest_transfer_type — Transaction type code for the cardholder account.

The activity type will be AD (adjustment) for both the source account and cardholder account. Use the transfer type codes that Galileo provided in a specially curated list of codes.

For example, if the cardholder has $25.00 in their account and the amount of the authorization is $30.00, you could transfer $5.00 into the cardholder account and return response_code: 00.



You can use real-time transfers to partially subsidize transactions. For example, you can build logic on your end to transfer a portion of the request amount from a central account when the request is from a certain MCC or merchant, and the rest of the amount would be drawn from the cardholder account. For example, if a request from the designated MCC arrives for $20, you can transfer $5 from the central account, and then the remaining $15 would automatically come from the cardholder account.

Galileo also offers Real-Time Funding, another method of transferring funds into a card account at authorization time, which is unrelated to real-time transfers.

Overriding limits

With the override_limit field you can override velocity limits that are set for the product. Use the amt_til_limit and nearest_limit fields to see how close an account is to exceeding a limit and which limit that would be.

Exercise caution with this type of override, however. Confirm with your bank that you are able to override limits and ensure that you have clearly defined which circumstances permit an override.

Balance inquiry responses

A typical balance inquiry is a separate transaction with trans_amount: 0.00 and transaction_type: Balance Inquiry. For these standalone inquiries, eligible_for_balance_return is always true. When Galileo holds the balance, Galileo returns 00 (success) and provides the balance that it has in available_funds. If you hold the account balance, populate available_balance with the current available balance and return response_code: 00. If you do not populate available_balance, Galileo will return the balance that it has on record.

If you have a Mastercard program, your product parameters control which merchant category codes (MCCs) can receive the account balance in the U.S., Canada, Mexico, and Colombia. For Visa programs, product parameters specify only whether balance inquiries are permitted. In the case of Visa transactions, balance inquiries are permitted only at ATMs. For both networks, balance inquiries are permitted only for card-present transactions.

With Mastercard, a "courtesy balance" request might also be included in a conventional authorization request, such as at a retail merchant where the merchant wants to print the balance on the receipt. In that case, eligible_for_balance_return: true and transaction_type contains a value other than Balance Inquiry. You may provide the balance in available_balance or Galileo will provide it.

When Galileo receives a balance inquiry, and product settings indicate that merchant is not eligible to receive the balance, Galileo responds with 05 (do not honor).

In the Authorized Transactions RDF, balance inquiries are identified by TRANSACTION CODE 10. These inquiries are not included in the Posted Transactions RDF, Program API responses, or the CST.

Fallback processing

When you do not respond to Galileo in time, Galileo can perform "fallback" processing, meaning that Galileo either responds with 05 (do not honor) for all transactions, or it returns the response that it has calculated, depending on how the APIFB product parameter is set. When this parameter is not set, Galileo returns 05 (do not honor) for all transactions that you do not respond to. When APIFB is set to Y, Galileo returns the response that it has calculated.

If Galileo will provide fallback processing and you are the system of record, you must devise a way to keep Galileo updated on your account balances so that Galileo can determine whether accounts have sufficient balance. You could send a batch file every few hours, for example.

When Galileo does not receive your response in time, it sends the OATO: Auth_API_Timeout Account Event webhook, and then Galileo sends you the AUFB: auth_fallback Authorization Event webhook to notify of both approved and denied fallback authorizations.

Stand-in processing

In some cases, the network must make a decision on Galileo's behalf, such as when Galileo does not respond to an authorization request from the network in time. The network may also process a transaction instead of sending it to Galileo first, for a variety of reasons. When you set up your relationship with the card network, you specify how and when the network will perform this stand-in processing (STIP). Based on these configuration and processing rules, the network may either deny or approve the transaction on Galileo's behalf.

When the network stands in to deny a transaction it notifies Galileo, and Galileo sends you the STPD: denied_auth_stip Authorization Event API webhook, provided that the STIPD parameter has been enabled. For Visa and Mastercard networks, the stip_info field in the event payload is populated with a reason code that describes why the network stood in for Galileo, as described in STIP Reason Codes. These denied transactions are not sent as Auth API webhooks, to avoid confusion regarding pre-denied advices, and are purely informational.

When the network stands in to approve a transaction it sends an advice to Galileo, which Galileo relays to you as an MTI 0120 or 0220 message. For Visa and Mastercard networks, the stip object in the webhook payload is populated with a reason code in the detail field, describing why the network stood in for Galileo, as shown in STIP Reason Codes. Galileo also sends you the BAUT: auth Authorization Event webhook.

STIP Reason Codes

Galileo not responding to the network is only one reason why the network performs STIP. Visa and Mastercard networks send a reason code when they stand in on behalf of Galileo. Galileo forwards this raw reason code in the STPD: denied_auth_stip Authorization Event API webhook (for denials) and BAUT: auth (for approvals). Some examples are listed below.

Consult the documentation from each network for more possible codes: the SMS POS Technical Specification for field 63.4 for Visa, and the Single Message System Specifications and Customer Interface Specification for field DE 60 for Mastercard.

Sample codes

Mastercard4000000Late response from issuer
Visa9020The response from issuer timed out
Visa9054Online CAM validation failed
Visa9061Internal system error or other switch-detected error condition

Auth API v3 webhook examples

Use these code samples (called Recipes) to help test your system. These samples come from actual Auth API v3 webhooks. You can also find these Recipes by clicking Recipes in the top navigation bar.

Authorization Events API

You can arrange for Galileo to send you Events API webhooks to notify of approvals and denials. See the Authorization Events index for the list of webhooks you can receive.

For common Authorization Events sequences, see Authorization events in the Events API Scenarios guide. Also see the examples in the Card Transactions Scenarios.

Galileo setup

These are some of the parameters that control the behavior of the Auth API. Also see Galileo setup in the Authorization guide for parameters that affect authorization behavior.

APIFBControls whether to perform fallback processing when your response to the webhook times out. When this parameter is N or not set, Galileo returns response code 05 (do not honor) for all fallback transactions. When this parameter is Y, Galileo returns the response code that it has calculated.
APPOLControls whether you review all transactions via the Auth API or only transactions that pass Galileo’s initial check.
AUAPIContains host:port addresses for servers that Galileo sends webhooks to.
AUAPRControls whether Galileo waits for a response to an advice. When set to Y or not set, Galileo waits for your response for all Auth API webhooks. When set to N, Galileo doesn't wait for your response for advice authorizations. (For all other authorizations, Galileo still waits for your response.)
MLAPIContains the host:port address of the server to use for machine-learning fraud detection.
RULAPControls whether to send a comma-separated list of rule names that caused a DENY or WARN for an authorization in the Auth API request payload. The DENY rules are in the rules_denied field and the WARN rules are in the rules_warned field. Valid only when using Galileo's fraud-detection process.