Auth API Field Detail

This guide contains details about some of the Auth API webhook fields.

With this guide you may also want to consider these resources:

• Authorization Controller API — General information about how the Auth API works.
• Authorization Response Codes — Codes that Galileo supports. You may also arrange with Galileo to send custom response codes, depending on your use case and business requirements.
• Authorization — General explanation of the authorization process at Galileo.

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

📘

Note

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 via the Auth API webhook. Special parameters must be set for these fields to be returned:

• ADVAF — Set this parameter to enable advanced_auth_api_fields.
• AAFAL — Specify Mastercard or Visa or both to get the fields for those networks only, or leave blank to get all networks.

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.

Example

"advanced_auth_api_fields": {
    "61": {
        "subfield 8": "0",
        "subfield 1": "1",
        "subfield 3": "2",
        "subfield 4": "5",
        "subfield 5": "1",
        "subfield 6": "0",
        "subfield 7": "8",
        "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 via 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 message:

• DE048 — Additional information
  • Subfield 71 — On-behalf service (OBS)
    • Subelement 1 — 18 (fraud scoring service)
    • Subelement 2 — C (fraud scoring service successful)
  • Subfield 75 — Fraud assessment prediction information. See Subfield 75 interpretation for more information.
    • Subelement 1 — 998 or 000
    • Subelement 2 — NM (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)

Example

"advanced_auth_api_fields": {
    "48": {
       "subfield 71": "18C",
       "subfield 75": "01039990202A10303806040211050200"
   	 },
    "60": {
       "subfield 1": "120"
    },
    "121": "000003"
}

Subfield 75 interpretation

The values in subfield 75 should be interpreted as follows:
01 03 999 02 02 A1 03 03 806 04 02 11 05 02 00

• Subelement 01 length = 03 value = 999
• Subelement 02 length = 02 value = A1
• Subelement 03 length = 03 value = 806
• Subelement 04 length = 02 value = 11
• Subelement 05 length = 02 value = 00

MSI Installments data

If your program is in Mexico, and you offer MSI Installments to your cardholders, you receive fields that contain information about the terms of the payment scheme. This data comes from DE048 and DE112. (In the settlement file, PDS0663 contains the same information as DE112 SE7.)

• DE048 — Additional data
  • Subelement 95 — Mastercard promotion code
    • MEXCTA — Installment switching service in Mexico
• DE112 — Additional data (national use)
  • Subelement 7 — MSI Installments payment data
    • Positions 1–2 (type of credit)
      • 03 — Without interest for the cardholder
    • Positions 3–4 (number of installments)
      • NN — Numbers 01 though 99
    • Positions 5–6 (grace period)
      • 00 — No grace period
      • 01 — One month
      • 02 — Two months
    • Positions 7–9 (transaction currency code)
      • 484 — Mexican peso

Example

"advanced_auth_api_fields": {
    "48": {
        "subfield 95": "MEXCTA"
        },
    "112": {
        "subfield 7": "030600484"
    }
}

Support for partial and purchase-only authorizations

DE048 Subfield 61 contains information about support of partial authorization at the POS as well as support for purchase-only approvals.

• DE048 — Additional data
  • Subelement 61 — POS Data, Extended Condition Codes
    • Subfield 1 — Partial Approval Terminal Support Indicator
      • 0 — Merchant terminal does not support receipt of partial approvals.
      • 1 — Merchant terminal supports receipt of partial approvals.
    • Subfield 2 — Purchase Amount Only Terminal Support Indicator
      • 0 — Merchant terminal does not support receipt of purchase only approvals.
      • 1 — Merchant terminal supports receipt of purchase only approvals.
    • Subfields 3-5 — Not currently returned

Example

"advanced_auth_api_fields": {
    "48": {
   	 "subfield 61": "11000"  
}

Local date and time

DE012 and DE013 contain the date and time at the POS.

• DE012 — Local time as HHMMSS, using the 24-hour clock
• DE013 — Local date as MMDD

Example

"advanced_auth_api_fields": {
    "12": "152045",
    "13": "1103"
}

Integrated circuit card (ICC) data

DE055 contains information pulled from the ICC (or EMV chip). Along with this information Galileo provides DE007, the transmission timestamp and DE048 SE33, the PAN mapping file information.

• DE007 — Transmission Date and Time. The date and time that a processor transmits any message (as opposed to the initiation of an entire transaction), expressed in Coordinated Universal Time (UTC). Format: MMDDhhmmss
• DE048 SE33 — PAN Mapping File Information
• DE055 — Integrated Circuit Card (ICC) System–Related Data
  • Tag 82 — Specifies which application functions are supported by the card.
  • Tag 95 — Terminal verification results (TVR). Status of the different functions as seen from the terminal. Not to be confused with the terminal_verification_results field elsewhere in the Auth API, which is derived from DE048 SE79SF1.
  • Tag 9F10 — Issuer Application Data (IAD)
  • Tag 9F34 — Cardholder Verification Method (CVM) results
  • Tag 9F36 — Application transaction counter (ATC)

Example

"advanced_auth_api_fields": {
    "7": "0224044522",
    "48": {
        "subfield 33": "R33061234569506COLCTA"
    },
    "55": {
       "tag 82": "3900",
       "tag 95": "0000008000",
       "tag 9F10": "<hex>",
       "tag 9F34": "<hex>",
       "tag 9F36": "0019"
    }
}

Visa CPS

Visa sends Custom Payment Service (CPS) information in Field 62. With CPS, Visa defines the criteria a transaction must meet to get the lowest possible interchange rates. Consult Visa documentation for more information on CPS.

Galileo can pass these subfields to you:

• 62.1 — Authorization characteristics indicator. A code used by the acquirer to request CPS evaluation.
• 62.11 — Multiple clearing sequence number. Total number of transactions in the sequence.
• 62.12 — Multiple clearing sequence count. The position of this transaction in the sequence.

Example

"advanced_auth_api_fields": {
    "62": {
        "subfield 1": "A",
        "subfield 11": "5",
        "subfield 12": "2"
        }
}

POS terminal PIN entry mode

DE022 subfield 2 contains information about the capability of the terminal device to support PIN entry. This same information is available by request in the de022 field (digit 3) of selected authorization events messages, in the RDFs as PIN ENTRY CAPABILITY and interpreted as text in the pin_entry_capability field of the Auth API webhook payload. See DE022 Codes for valid values.

Example

"advanced_auth_api_fields": {
    "22": {
        "subfield 2": "1"
     }
}

Banknet Reference Number

The Banknet Reference Number is generated by the Mastercard network for each originating message it routes. The reference number is 6–9 digits long and is guaranteed to be a unique value for any transaction within the specified financial network on any processing day.

Example

"advanced_auth_api_fields": {
    "63”: {
        "subfield 2”: “123456”
    }
}

Replacement amounts

DE095 contains the “actual amount” subfields necessary to perform a partial or full reversal of a transaction.

Galileo can pass these subfields to you:

• DE095 — Replacement amounts
  • Subfield 1 — Actual transaction amount.
  • Subfield 2 — Actual settlement amount in the settlement currency. All settlement amounts are specified in U.S. dollars.
  • Subfield 3 — Actual amount in the cardholder billing currency.

Example

"advanced_auth_api_fields": {
    "95": {
        "subfield 1": "000000002700",
        "subfield 2": "000000000000",
        "subfield 3": "000000002700"
        }
}