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:

  • <a href="ref:webhook_authorization_post_2" target="_blank">Version 2</a>

  • <a href="ref:webhook_authorization_post_3" target="_blank">Version 3</a>

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

  • <a href="doc:about-card-transactions" target="_blank">About Card Transactions</a>

  • <a href="doc:authorization" target="_blank">Authorization</a>

To see how specific transaction types are represented in the Events API, Program API and <<glossary:RDF>> data alongside Auth API data, see the <a href="doc:card-transaction-scenarios-index" target="_blank">Card Transactions Scenarios</a>. For actual Auth API webhooks, see [Auth API v3 webhook examples](🔗) on this page.

## Prior setup

To coordinate with Galileo to set up Auth API, you need to provide:

  • Proof of bank approval

  • A signed Statement of Work ("SOW")

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

Warning

Version 3 is a breaking change from version 2.

## Requirements

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 <a href="ref:api-reference-auth-api-about-auth-api#security" target="_blank">Security</a> in the Auth API reference for details.

  • The webhook payload is sent as an HTTP POST using HTTP over TLS 1.2.

  • 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 <a href="doc:card-transaction-scenarios-index" target="_blank">Card Transactions Scenarios</a> 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 messages are in <<glossary:EBCDIC>> format, which does not support international character sets.) 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

Note

Galileo is not an issuer—your partner bank issues your cards, and Galileo is the processor; however, Galileo fulfills the issuer role when exchanging ISO 8583 messages with the network.

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.

Note

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.

Descriptionauth_typetransaction_typemti
Authorization requestAuthAuth0100 (credit rails)<br>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)<br>0220 (debit rails)
AdjustmentAdviceAdjustment0200
Notification of a reversalReversalAuth0420
Reversal of a card loadReversalPayment0220

<!--Also see Transaction codes mapped to Auth API values for how various `auth_type`, `transaction_type`, and `subnetwork` combinations map to transaction codes.....................-->

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

See <a href="doc:auth-api-validation-checks" target="_blank">Auth API Validation Checks</a> for details on the various response codes that Galileo calculates when evaluating an authorization request.

## Additional field information

See the _Auth API Field Detail_ guide for more information on these topics:

##### Tokenization requests
  • <a href="doc:auth-api-field-detail#tokenization-requests" target="_blank">Tokenization requests</a> — Details on tokenization requests

##### IIAS fields
  • <a href="doc:auth-api-field-detail#iias-fields" target="_blank">IIAS fields</a> — Information returned by an inventory information approval system (IIAS)

##### Advanced Auth API fields
  • <a href="doc:auth-api-field-detail#advanced-auth-api-fields" target="_blank">Advanced Auth API fields</a> — Various DEs specially parsed and included by request

## 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. See the <a href="ref:api-reference-events-authorization-response-codes" target="_blank">Authorization Response Codes</a> enumeration for the full list of codes.

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

If you agree with the `response_code` that Galileo sends in the webhook, or if it is a `response_code` that you are not allowed to override, your response should echo the Galileo response code. For example, if Galileo sends `response_code: 00`, and you do not want to override it, this should be your response:



Your response must be in JSON format. More sample responses are in the reference (<a href="ref:webhook_authorization_post_2" target="_blank">Version 2</a>, <a href="ref:webhook_authorization_post_3" target="_blank">Version 3</a>). 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.

### Overrides

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

  • `46` — Suspected fraud (Visa only)

  • `51` — Insufficient funds

  • `59` — Suspected fraud

  • `63` — Suspected fraud (Mastercard only)

Overriding these response codes requires bank approval. To add more response codes to override after initial setup, you will need additional bank approval. For example, you might want to approve tokenization requests for Mastercards that are in `status: W` (waiting for payment). In that case, you would get bank approval to override `response_code: 78` when `transaction_type: Tokenization` and `card_status: W`.

When overriding a response code to deny a transaction, card networks advise that you not use the generic `response_code: 05` (do not honor) unless other, more-specific response codes do not apply. For example, if Galileo calculates `response_code: 10` (partial approval) and you don't want to approve those funds, use `response_code: 51` (insufficient funds) instead of `response_code: 05`.

When you have obtained bank permission for the overrides, Galileo updates your settings to specify which overrides you can perform. If you attempt to perform an override that is not in your settings, then Galileo performs the action specified in the APIFB parameter ([fallback processing](🔗)).

#### 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. See <a href="ref:api-reference-avs-codes" target="_blank">AVS Codes</a> for valid values.

#### Overriding insufficient funds

When Galileo returns `51` (insufficient funds), you can override it in one of these ways:

  • [Approval override](🔗) — Use only when you hold the ledger for your program.

  • [Partial authorization](🔗) — Valid only when the merchant supports partial authorizations.

  • [Real-time transfers](🔗) — You must set up a transfer account for this option.

##### Approval override

If you hold the ledger for your program, Galileo may not have accurate balance information. If Galileo returns `51`, and your ledger shows that there are sufficient funds, you should respond with `response_code: 00`. It is not necessary to provide the correct balance in the response.

##### 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 <<glossary: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 (otypes) that Galileo provided in your Funds Flow document.

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

Tip

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.

Note

Another method to transfer funds into card accounts at authorization is real-time funding. See <a href="doc:about-real-time-funding#comparison-with-other-methods" target="_blank">Comparison with other methods</a> in the _About Real-Time Funding_ guide for an explanation of the difference.

#### 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 _balance inquiry_ is a standalone authorization request with `trans_amount: 0.00` and `transaction_type: Balance Inquiry`. (In some jurisdictions such as Mexico, a small fee may be included.) For these 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 product settings indicate that the merchant is not eligible to receive the balance, Galileo responds with `05` (do not honor). 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.

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 <<glossary:CST>>.

A _balance return_ is part of a conventional authorization request for a purchase amount, such as when the merchant wants to print the remaining balance on the receipt. In that case, `eligible_for_balance_return: true` and `transaction_type` contains a value other than `Balance Inquiry`.

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

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

Note

There is no retry mechanism for Auth API webhooks.

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 <a href="ref:api-reference-events-api-auth-api-timeout" target="_blank">`OATO: Auth_API_Timeout`</a> Account Event webhook, and then Galileo sends you the <a href="ref:api-reference-events-api-auth-fallback" target="_blank">`AUFB: auth_fallback`</a> 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.

After the network performs a STIP transaction, it sends an advice notification to Galileo. If the transaction changes the available balance, Galileo relays the advice to you as an MTI 0120 or 0220 message. If the advice does not change the balance, Galileo does not send an Auth API webhook.

Galileo also sends event messages according to the type of STIP transaction:

  • <a href="ref:api-reference-events-api-auth-stip-advice" target="_blank">`STPA: auth_stip_advice`</a> — Mastercard or Visa approval or denial. The STIPA parameter must be enabled. If `is_stip_denial: Y`, then the transaction was denied and no Auth API webhook was sent.

  • <a href="ref:api-reference-events-api-auth" target="_blank">`BAUT: auth`</a> — Visa approvals. No STIP information is provided with this message.

  • <a href="ref:api-reference-events-api-auth-stip-info" target="_blank">`STPD: auth_stip_info`</a> — Mastercard or Visa non-financial STIP transactions, which do not affect the available balance. The STIPD parameter must be enabled. An Auth API webhook is not sent for these transactions.

### STIP Reason Codes

Galileo not responding is only one reason why networks perform STIP. To indicate why they performed stand-in processing, Visa and Mastercard networks send a reason code in the advice notification. Galileo forwards this reason code in these fields:

  • `stip_info` — In the `STPD: auth_stip_info` event message

  • `stip_advice` — In the `STPA: auth_stip_advice` event message

  • `stip: {detail}` — In the Auth API webhook

Consult the documentation from each network to interpret the codes:

  • Visa _SMS POS Technical Specification_ for field 63.4

  • Mastercard _Single Message System Specifications and Customer Interface Specification_ for DE 60

#### Sample codes

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

## Authorization Events API

You can arrange for Galileo to send you <a href="ref:api-reference-events-api-about-events-api" target="_blank">Events API</a> webhooks to notify of approvals and denials. See the <a href="ref:api-reference-events-api-authorization-events-index" target="_blank">Authorization Events index</a> for the list of webhooks you can receive.

For common Authorization Events sequences, see <a href="doc:events-api-scenarios#authorization-events" target="_blank">Authorization events</a> in the _Events API Scenarios_ guide. Also see the examples in the <a href="doc:card-transaction-scenarios-index" target="_blank">Card Transactions Scenarios</a>.

## Galileo setup

These are some of the parameters that control the behavior of the Auth API. Also see <a href="doc:authorization#galileo-setup" target="_blank">Galileo setup</a> in the _Authorization_ guide for parameters that affect authorization behavior.

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

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

Auth API v3: Approved transaction
Open Recipe

Auth API v3: AVS check with in-app purchase
Open Recipe

Auth API v3: Failed PIN at ATM
Open Recipe

Auth API v3: Failed PIN count exceeded
Open Recipe

Auth API v3: Partial approval
Open Recipe

Auth API v3: Merchant credit
Open Recipe

Auth API v3: Lost card
Open Recipe

Auth API v3: Card frozen and load not permitted
Open Recipe

Auth API v3: Velocity limit exceeded at ATM
Open Recipe

Auth API v3: Bad CVV2 with insufficient funds
Open Recipe

Auth API v3: Expiry date mismatch
Open Recipe

Auth API v3: Mobile wallet provisioning request, red path
Open Recipe

Auth API v3: Mobile wallet provisioning request, green path
Open Recipe

Auth API v3: Balance inquiry
Open Recipe

Auth API v3: Reversal
Open Recipe

Auth API v3: Completion (advice) at gas pump
Open Recipe

Auth API v3: 3-D Secure transaction
Open Recipe

Auth API v3: Fraud rules engine denies auth
Open Recipe

Auth API v3: Adjustment from an ATM
Open Recipe

Auth API v3: Visa merchant credit over Mastercard rails
Open Recipe

Auth API v3: Denied cash advance
Open Recipe

Auth API v3: Successful card load
Open Recipe

Auth API v3: Merchant mobile wallet check
Open Recipe

Auth API v3: Denied international incremental authorization
Open Recipe

Auth API v3: STIP notification of merchant credit
Open Recipe