openapi: 3.2.0 info: title: Auth API Webhook API description: '# Overview Auth API is a webhook that allows clients to participate in the authorization decision making process.' version: 2.0.0 servers: - url: https://example.client.domain.com description: You will provide the base URL you would like to use for Auth API. The endpoint should use HTTPS. security: - bearerAuth: [] tags: - name: Auth API Webhook paths: /basepath/Authorization: post: summary: Auth API Webhook 2.0 description: 'With the Auth API 2.0 webhook, you can participate in authorization decisions. For this webhook there is only one verb: `POST`. SoFi Tech Solutions sends information about the authorization request in the body of the HTTP request, in JSON. Your decision should be in the body of the HTTP response. In the authorization information that we send, the `response_code` is the current response code to be returned to the merchant, unless you override it. Use the `response_code` field in the HTTP response body to override the authorization response code, as desired. See the Authorization Controller API guide for more information. > 📘 About the field properties > > SoFi Tech Solutions initializes the webhook payload by setting all fields to `null`. As values come in with the ISO 8583 authorization request, we populate the respective payload fields with the data the network sends, which can include empty strings (`" "`). This documentation shows the field properties (data type, nullability, required) that are most likely. However, variations by network and transaction type mean that a few of the values passed in the webhook payload can vary from what is shown here.' operationId: webhook_authorization_post_2 tags: - Auth API Webhook parameters: - name: X-Request-ID in: header description: A unique identifier for the HTTP request. schema: type: string format: uuid required: true requestBody: description: Information about the authorization request. required: true content: application/json: schema: type: object properties: auth_type: type: string description: 'All transactions are grouped into three basic message types: * `Auth` — Authorization request. MTI x1xx (authorization or preauthorization over credit rails or preauthorization over debit rails) or x2xx (authorization over debit rails). * `Advice` — Notification of a completed transaction. MTI xx2x. Only a `00` response code is permitted. * `Reversal` — A reversal of a previous authorization. MTI x4xx. May or may not reference the previous authorization.' enum: - Auth - Advice - Reversal transaction_type: type: string description: 'The transaction type indicates at a lower level what kind of transaction this is. This field is used to differentiate merchant credits, ATMs, balance inquiries, etc. * `Preauth` — A preauthorization for an estimated amount. Often followed by a completion advice. * `Auth` — Conventional authorization request. Also used with advices and reversals. * `ATM` — ATM withdrawal. * `Cash Advance` — Cash advance from a teller. * `Balance Inquiry` — Balance inquiry from an ATM. * `Merchant Credit` — A credited amount from a merchant. Usually does not reference a previous authorization. * `Adjustment` — Debit adjustment, unrelated to a previous authorization. The merchant is adjusting a cardholder balance. * `Payment` — Loading funds onto a card. * `Tokenization` — A request to tokenize a card for use in a mobile wallet or a request from a merchant to validate a tokenized card for payment.' enum: - Preauth - Auth - ATM - Cash Advance - Balance Inquiry - Merchant Credit - Adjustment - Payment - Tokenization id: type: string description: "Unique identifier for this authorization. \n\nExample: `\"DHWJtI8zRjuDcgF8hru3oQ\"`" example: DHWJtI8zRjuDcgF8hru3oQ timestamp: type: string description: 'Date and time when the webhook was sent by SoFi Tech Solutions. Format is ``, where `timestamp` is `YYYYMMDD:HHMMSS` and `timezone` is always `MST`, which is Arizona time (GMT -0700). Example: `"20250315:121504MST"`' example: 20250315:121504MST network: type: string description: 'Card network name. Possible values: * `Visa` * `Allpoint` * `Discover` * `Mastercard` * `Star` * `Pulse`' enum: - Visa - Allpoint - Discover - Mastercard - Star - Pulse subnetwork: type: string description: 'The subnetwork name. This is the same as `network` if there is no subnetwork. Possible values: * `Visa` * `Visa Interlink` * `Visa PLUS` * `Mastercard Banknet` * `Mastercard Debit Switch` * `Discover` * `Allpoint` * `Star` * `Star MoneyPass` * `Star Presto` * `Pulse`' enum: - Visa - Visa Interlink - Visa PLUS - Mastercard Banknet - Mastercard Debit Switch - Discover - Allpoint - Star - Star MoneyPass - Star Presto - Pulse account: type: object properties: xid: type: integer description: 'Internal ID for the account. Example: `5398373`' example: 5398373 cad: type: integer description: 'System-generated ID for the card. This ID has a 1:1 relationship with the <>. Example: `72450868`' example: 72450868 prn: type: string minLength: 12 maxLength: 12 description: 'Payment reference number for the account. 12 digits. Example: `"999200002022"`' example: '999200002022' product_id: type: - integer - 'null' description: 'Product ID for the account, as provided by SoFi Tech Solutions. Example: `2577`' example: 2577 program_id: type: - integer - 'null' description: 'Program ID for the account, as provided by SoFi Tech Solutions. Example: `566`' example: 566 pan: type: string description: 'Last four digits of the <> of the card. Example: `"5198"`' example: '5198' account_status: type: string description: 'Account status code. See the possible values in the Account Statuses enumeration. Example: `"N"`' card_status: type: string example: N description: 'Card status code. See the possible values in the Card Statuses enumeration. Example: `"N"`' expiration_date: type: string minLength: 4 maxLength: 4 description: 'Card expiration date (format `YYMM`). Example: `"2103"`.' example: '2103' track_expiration_date: type: - string - 'null' minLength: 4 maxLength: 4 description: 'The expiration date (format: `YYMM`) that was read from the card''s magnetic stripe and sent in the ISO message, if present and applicable. For example, this field will not be present for a card-not-present transaction. Example: `"2103"`' example: '2103' merchant_supplied_expiration_date: type: - string - 'null' minLength: 4 maxLength: 4 description: 'The expiration date (format: `YYMM`) supplied by the merchant, if present and applicable. Example: `"2103"`' example: '2103' required: - xid - cad - prn - pan - account_status - card_status - expiration_date - track_expiration_date - merchant_supplied_expiration_date amounts: type: object description: 'The amounts are always unsigned. To calculate the sign for an amount, start with a factor of –1, and then apply another factor of –1 for each of the following criteria: * `"auth_type": "Reversal"` * `"transaction_type": "Merchant Credit"` * `"transaction_type": "Payment"` Amount fields may not display a numeric value for non-active cards. Instead, the string `"none"` could be displayed.' properties: currency: type: - string - 'null' minLength: 3 maxLength: 3 description: 'The currency code for the amounts, unless otherwise indicated. This is the currency of the cardholder account. ISO 4217 Numeric Currency Code. 3 digits. Example: `"840"`' example: '840' trans_amount: type: string description: 'Transaction amount. Full amount of the authorization request, including upcharges and fees and after any currency conversion is performed. Example: `"12.40"`' example: '12.40' partial_amount: type: string default: '0.0' description: 'If `partial_supported: true` and `response_code` is `10` or `87`, this is the amount of the partial approval. Example: `"10.00"`' example: '10.00' cashback_amount: type: string default: '0.0' description: 'Cashback amount requested. This amount is included in `trans_amount`. Example: `"5.00"`' example: '5.00' fee_amount: type: string default: '0.0' description: 'Amount of any fees. This amount is included in `trans_amount`. Example: `"1.50"`' example: '1.50' available_funds: type: string description: 'The card''s available balance before this transaction is applied. If this authorization request is approved, the card''s available balance is affected within a few milliseconds after the approval is sent to the network. Keep in mind that this is the available balance known to SoFi Tech Solutions—if you are the system of record for your program, refer to your records to determine whether the account has sufficient funds. Example: `100.00`' example: 100 amt_til_limit: type: string default: '0.0' description: 'Amount remaining before `nearest_limit` is reached. Example: `502.80`' example: 502.8 nearest_limit: type: - string - 'null' description: 'The name of the first limit that would be reached if a partial authorization or denied authorization is overridden via the `override_limit` field. This field is present only when the limit would be reached in overriding the authorization. Example: `"PCL Daily Limit"`' example: PCL Daily Limit local_currency: type: string minLength: 3 maxLength: 3 description: 'ISO 4217 numeric currency code for `local_currency_amount`, which is the currency at the point of sale. 3 digits. Example: `"124"`' example: '124' local_currency_amount: type: string default: '0.0' description: 'Amount of the request in the currency at the point of sale. Upcharges and fees are not included. Example: `"21.00"`' example: '21.00' settle_currency: type: - string - 'null' minLength: 3 maxLength: 3 description: 'ISO 4217 numeric currency code for `settlement_currency_amount`. To understand what a settlement currency is, see Multicurrency BINs. 3 digits. Example: `"978"`' example: '978' settle_currency_amount: type: string default: '0.0' description: 'Amount of the request in the settlement currency. Upcharges and fees are not included. Example: `"17.00"`' example: '17.00' billing_currency: type: string minLength: 3 maxLength: 3 description: 'ISO 4217 numeric currency code for `billing_currency_amount`. Example: `840`' example: 840 billing_currency_amount: type: string default: '0.0' description: 'The amount of the transaction in the billing currency, which is the currency of the card account. Example: `"12.40"`' example: '12.40' local_surcharge_amt: type: string default: '0.0' description: 'The surcharge amount in the currency at the point of sale. Example: `"0.50"`' example: '0.50' settle_surcharge_amt: type: string default: '0.0' description: 'The surcharge amount in the settlement currency. Example: `"0.75"`' example: '0.75' settle_exchange_rate: type: string description: 'The factor used to convert from the local request amount to the settlement amount. The string has the pattern ``. The first digit specifies how many places from the right the decimal is moved. For example, `69985022` translates to an exchange rate of 9.985022%. Example: `"69985022"`' example: '69985022' exchange_rate: type: string description: 'The factor used to convert from the local request amount to the billing amount. The string has the pattern ``. The first digit specifies how many places from the right the decimal is moved. For example, `69985022` translates to an exchange rate of 9.985022%. Example: `"65991234"`' example: '65991234' upcharge_amount: type: string default: '0.0' description: 'The upcharge amount, which is included in `trans_amount`. Example: `"75.00"`' example: '75.00' required: - currency - trans_amount - cashback_amount - fee_amount - available_funds - amt_til_limit - upcharge_amount mcc: type: integer description: 'Merchant category code. This value does not include leading zeros. Example: `5992`' example: 5992 digital_commerce_data: type: object description: '_Mastercard only_. Contains data regarding a digital commerce transaction. Derived from DE048SE48. See Digital Commerce Solutions Indicators for more information. ' properties: entity_type_name: type: string description: 'SF3. The check-in entity type and entity name. Example: `"202010030220"` ' example: '202010030220' domain_id: type: string description: 'SF1. The entity responsible for populating the other fields in this object. Example: `"01"` ' example: '01' program_id: type: string description: "SF2. The specific digital commerce program.\n \n\nExample: `\"01\"`\n" example: '01' checkin_method: type: string description: 'SF4. The methods that a check-in entity applies to validate cardholder presence. **Required** when `program_id: 04`. Example: `" "` ' example: null merchant: type: object properties: acquirer_id: type: - string - 'null' description: 'The acquiring institution ID. Example: `"406160"`' example: '406160' terminal_id: type: - string - 'null' description: 'The ID for the device that acquired the card information. Example: `"A1Z23B99"`' example: A1Z23B99 merchant_id: type: - string - 'null' description: 'The merchant ID, as assigned by the network. Example: `"39AJKEO30634KVN3"`' example: 39AJKEO30634KVN3 merchant_description: type: - string - 'null' description: 'The merchant description. Example: `"123 WIDGETS MERCHANT BEVERLY HILLS CA"`' example: 123 WIDGETS MERCHANT BEVERLY HILLSCA merchant_country: type: - string - 'null' description: 'ISO 3166-1 country code for the country where the merchant is located. 3 digits. Example: `"840"`' example: '840' merchant_postal_code: type: - string - 'null' description: 'Postal code, nine characters. Left-justified and padded with zeros. If there are nine zeros, then no postal code was provided. Example: `"902100000"`' example: '90210' merchant_state: type: - string - 'null' description: 'Two-letter state or provincial designator for the merchant''s location. Example: `"NV"`' example: NV terminal_network: type: - string - 'null' description: 'Network to which the terminal belongs, Possible values are `VPA` (Visa PLUS Alliance), `Allpoint`, or `None` (another network). If you are not configured to receive this data, the value will always be `None`. Example: `"VPA"`' example: VPA enum: - Allpoint - VPA - None required: - acquirer_id - terminal_id - merchant_id - merchant_description - merchant_country - merchant_postal_code - merchant_state - terminal_network mti: type: string description: 'Message-type indicator, as defined by ISO 8583. See Message types in the _Authorization Controller API_ guide. Example: `"0200"`' example: '0200' transaction: type: object description: Information about the transaction properties: recurring: type: string description: 'Whether a transaction is recurring: `Y` or `N`. Example: `"N"`' example: N cardholder_present: type: string description: 'Whether the physical card was present at the point of sale: `Y` or `N`. Example: `"Y"`' example: Y transaction_initiator_code: type: string description: '*Mastercard only.* Whether the transaction was initiated by the cardholder or the merchant. Populated only when DE048 subfield 22 is present in the authorization request. See CIT and MIT Indicators for more information. Example: `"M101"`' example: M101 is_advance_payment: type: boolean description: _Visa only_. Field 126 SE 13. Whether the transaction is an advance payment, meaning that the merchant secures the payment before the goods or services are available. example: true required: - recurring - cardholder_present validation_results: type: object properties: cvv1: type: string description: 'Result of <>1 validation. Possible values: * `Y` — Validated * `F` — Failed * `N` — Not present' enum: - Y - F - N cvv2: type: string description: 'Result of CVV2 validation. Possible values: * `Y` — Validated * `F` — Failed * `N` — Not present' enum: - Y - F - N cvv3: type: string description: 'Result of CVV3 validation. Possible values: * `Y` — Validated * `F` — Failed * `N` — Not present' enum: - Y - F - N pin: type: string description: 'Result of PIN validation. Possible values: * `Y` — Verified * `F` — Failed * `L` — Locked * `M` — PIN not set * `B` — Blocked * `N` — No PIN was passed' enum: - Y - F - L - M - B - N arqc: type: string description: 'Result of validating the authorization request cryptogram for an EMV chip. Possible values: * `Y` — Validated * `F` — Failed * `N` — Not present' enum: - Y - F - N offline_pin: type: string description: 'Result of validating the offline PIN. Possible values: * `Y` — Validated * `F` — Failed * `N` — Not present * `E` — Offline PIN attempts exceeded * `P` — Ignored due to risk params' enum: - Y - F - N - E - P avs_result: type: string description: 'Result of the <> check. See AVS Codes for valid values. Example: `"Y"`' enum: - Y - A - Z - N - M - T - X - S - U - B - C - D - R aav: type: string description: 'Result of validating the <>/<>. Possible values: * `Y` — Validated * `F` — Failed * `N` — Not present' enum: - Y - F - N required: - cvv1 - cvv2 - cvv3 - pin - arqc - offline_pin - avs_result - aav avs_data: type: object description: When the authorization includes an <> request, this object contains the data that SoFi Tech Solutions used to calculate the AVS response. properties: zip: type: string description: 'Postal code provided by the cardholder. Example: `"84121"`' example: '84121' address: type: string description: 'Numbers in the first address line, provided by the cardholder. Example: `"1235"`' example: '1235' required: - zip - address international: type: boolean description: 'Whether this is an international transaction. ' example: true response_code: type: string description: 'Authorization response code, which specifies whether a transaction is approved or denied. See the Authorization Response Codes enumeration for possible values. Example: `"05"`' example: '05' auth_id: type: integer description: 'System-generated ID for the authorization. Use this ID to track the transaction throughout the system. For an explanation of how these IDs are generated, see Authorization identifiers in the _Transaction IDs_ guide. Example: `13371854`' example: 13371854 partial_supported: type: boolean description: Whether the merchant supports partial authorizations. example: true stip: type: object description: This object is present when a <> transaction is processed by the network. See Stand-in processing in the _Authorization Controller API_ guide for more information. properties: detail: type: string description: 'Advice reason code relayed from the network, which provides information on the STIP transaction. See Advice Reason Codes for valid values. Example: `"4000000"` or `"9020"`' example: '9020' stip_decision: type: string description: 'The Authorization Response Code that was returned to the merchant by the STIP process. Example: `"00"`' additional_detail: type: - string - 'null' description: 'More information about the STIP transaction. See STIP Additional Detail for valid values. Example: `"000003"`' is_stip_denial: type: string description: 'Whether the transaction was denied by the STIP process: `N` (approved). Denied STIP transactions do not trigger an Auth API message. Example: `"N"`' incremental_auth: type: boolean description: 'If this authorization is part of an an incremental sequence, this field is `true` and `original_id` contains the `auth_id` of the previous authorization in the sequence. ' example: true entry_type: type: string description: 'Method of entering the <>, also known as <> entry mode. See DE022 Codes to correlate with the numerical values. Possible values: * `Card Not Present` — Online, mail order or telephone order * `Card On File` — _Mastercard only._ Card number is kept on file * `E-Commerce` — _Mastercard only._ The card was used on an ecommerce site * `EMV Chip` — The card has an EMV chip that was inserted in an EMV slot * `EMV Contactless` — Contactless transaction with EMV chip card * `EMV Fallback` — Unable to use the EMV chip: fallback to magstripe * `Magnetic Stripe` — The magnetic stripe was read * `Contactless` — Contactless transaction with magstripe card * `Manual` — Manually entered information * `Other` — None of the above' enum: - EMV Chip - EMV Contactless - EMV Fallback - Magnetic Stripe - Contactless - Card Not Present - Manual - Other pin_entry_capability: type: string description: 'Condition of the PIN pad at the point of sale. See DE022 Codes to correlate with the numerical values. Possible values: * `Capable` — Terminal has PIN-entry capability * `Incapable` — Terminal has no PIN-entry capability * `Inoperative` — Terminal has PIN-entry capability but it is not working * `Other` — Unknown PIN-entry capability, or not applicable.' enum: - Capable - Incapable - Inoperative - Other payment_info: type: object description: When `transaction_type` is `Payment`, the name of the sender and fund source, if provided in the request. properties: sender_name: type: - string - 'null' description: 'Name of the sender of the payment. Example: `"John Doe"`.' example: John Doe fund_source: type: - string - 'null' description: 'Source of the payment. Example: `"Visa Prepaid"`.' example: Visa Prepaid original_id: type: integer description: 'The `auth_id` of a previous authorization that is linked to this authorization. For reversals or completions, this is the `auth_id` of the authorization that is being reversed or completed. For incremental sequences, this is the `auth_id` of the previous authorization in the sequence. Example: `13663253`' example: 13663253 risk_score: type: string description: 'The risk score provided by the network. Mastercard range: 0–999, Visa range: 01–99. Higher values indicate higher risk. Product settings determine whether the threshold was exceeded. Example: `"23"`' example: '23' token_type: type: - string - 'null' description: 'If this is a tokenized transaction, its type. Possible values: * `Apple Inc` * `Google Inc.` * `Masterpass` * `Merchant` * `Microsoft` * `Samsung Corporation` * `Visa Checkout`' enum: - Apple Inc. - Google Inc. - Masterpass - Merchant - Microsoft - Samsung Corporation - Visa Checkout rules_denied: type: array description: 'Valid only when using our fraud-rules engine. List of fraud rules that caused a decline. Set the RULAP product parameter to receive these rules. Example: `["hr_crypto:DENY", "intl_cnp_ecom:DENY"]`' items: type: string rules_warned: type: array description: 'Valid only when using our fraud-rules engine. List of fraud rules that caused a warning. Set the RULAP product parameter to receive these rules. Example: `["dom_cp:WARN"]`' items: type: string response_code_list: type: array description: 'List of response codes that SoFi Tech Solutions has computed. This list does not contain `"00"`. May be empty. Example: `["05", "51"]`.' items: type: string description: 'Authorization response code, which specifies whether a transaction is approved or denied. See the Authorization Response Codes enumeration for possible values. Example: `"05"`' example: '05' bai: type: string description: 'Business application identifier. _Visa only._ See the Business Application Identifier enumeration for possible values. Example: `"FD"`' example: FD risk_code: type: string description: '_Mastercard only_. Fraud reason code. Indicates the key factors that influenced the value in `risk_score`. Example: `"58"`' ecommerce: type: object description: This object contains information related to <> authentication, if the website supported 3DS. Included in this information is the result of validating the <> for Mastercard or the <> for Visa. For detailed information about these fields, refer to The ecommerce object in the _3-D Secure Access Control Server_ guide. properties: is_ecommerce: type: - boolean - 'null' description: Whether the transaction took place on a website that supports 3DS. example: true raw_eci: type: string description: 'The electronic commerce indicator (ECI) that is sent in the authorization request. Example: `"212"`' example: 212 aav_indicator: type: string description: 'Universal Cardholder Authentication Field (UCAF). Example: `"kE"`' example: kE merchant_asserts_data_protection: type: - boolean - 'null' description: Whether the merchant or acquirer claims that the connection between the ecommerce site and the cardholder was encrypted. example: true merchant_asserts_authentication_attempted: type: - boolean - 'null' description: Whether the merchant or acquirer claims that 3DS authentication was attempted. example: None merchant_asserts_authenticated: type: - boolean - 'null' description: Whether the merchant or acquirer claims that the 3DS authentication was successful. example: false merchant_authentication_assertions_validated: type: - boolean - 'null' description: Validation results of the merchant's assertions. example: true cavv_result_code: type: - string - 'null' description: '_Visa only_. A code that indicates the outcome of CAVV validation. See CAVV Result Code for valid values. Example: `"B"`' example: B required: - is_ecommerce eligible_for_balance_return: type: boolean description: 'Whether the cardholder''s balance can be returned. This field is always `true` when `transaction_type: Balance Inquiry`. See Balance-inquiry responses in the _Authorization Controller API_ guide for information on returning balances in the response to this message.' example: true emv: type: object description: Additional EMV information. Also see EMV entry types under `entry_type` and EMV-related fields under `validation_results`. properties: is_emv: type: boolean description: This field is `true` if the `entry_type` is `EMV Chip` or `EMV Contactless`. When this value is `true`, the remaining fields below will be present, although they may be only partially populated, depending on the card network or EMV entry type. example: true brand: type: string description: 'Type of EMV. Possible values: * `visa` * `mastercard` * `discover` The card network may not match the EMV brand. For example, Visa EMV technology can be used on a card whose BIN is serviced through Allpoint.' example: visa enum: - visa - mastercard - discover terminal_verification_results: type: object description: 'This object interprets the status bits sent by the payment terminal, based on what happened during the transaction, such as whether the cardholder entered a valid PIN. Selected bits of the TVR have been separated out into the Boolean fields below. Use these fields with caution: There can be inconsistencies between different networks, and some bits are not applicable for certain entry types such as `EMV Contactless`. For example, Discover states that byte 3, bits 4 and 5 should be ignored for contactless transactions.' properties: raw: type: - string - 'null' description: 'The raw TVR (as a hex string) that was received in the ISO 8583 message, if present. If not present this field is null and the remaining fields in the `terminal_verification_results` object will not be present. Example: `"0000000000"`' online_pin_entered: type: boolean description: '_Byte 3, bit 3._ Whether a PIN is being sent in the ISO message for validation instead of using offline validation (where the EMV chip on the card validates the PIN). ' example: true pin_required_pad_pres_but_no_pin_entered: type: boolean description: _Byte 3, bit 4._ Whether the merchant or cardholder chose to bypass PIN entry, and the PIN pad was operational. example: false pin_required_no_pad_or_bad_pad: type: boolean description: _Byte 3, bit 5._ Whether a PIN was required but there was no PIN pad, or the PIN pad wasn't working. example: true pin_try_limit_exceeded: type: boolean description: _Byte 3, bit 6._ Whether the PIN-try limit was exceeded. For example, the terminal read the PIN-try counter on the chip and it was zero. example: false cardholder_verification_not_successful: type: boolean description: _Byte 3, bit 8._ Whether the terminal indicates that cardholder verification was not successful. example: false required: - raw required: - is_emv version: type: string description: 'Auth API version of this webhook. Example: `"2.0"`' example: '2.0' iias_info: type: object description: _Visa only_. Present when the items or services being purchased include eligible medical expenses. Derived from Field 54 and Field 62. This object is present only when <> information is included with the authorization request. For more information, see IIAS fields in the _Auth API Field Detail_ guide. properties: iias_indicator: type: string description: '`M` indicates that the card is an <>, <>, or <> card. Field 62.4. Example: `"M"`' merchant_verification_value: type: string description: 'IIAS merchant verification value for the <>-certified merchant location. Field 62.20. Example: `"1234560000"`' qualified_healthcare_products_total: type: string description: 'Amount of `trans_amount` that qualifies as a healthcare product or service. Field 54, amount type 4S. Example: `"64.87"`' rx_total: type: string description: 'Amount that is prescription medication. Field 54, amount type 4U. Example: `"64.87"`' vision_total: type: string description: 'Amount that is vision-related. Field 54, amount type 4V. Example: `"0.00"`' clinic_total: type: string description: 'Amount that is a clinic visit. Field 54, amount type 4W. Example: `"0.00"`' dental_total: type: string description: 'Amount that is dental-related. Field 54, amount type 4X. Example: `"0.00"`' advanced_auth_api_fields: type: object description: 'Selected subfields parsed from the ISO 8583 message. These fields are sent only when ADVAF is set and only by arrangement with SoFi Tech Solutions. See Advanced Auth API Fields for more information. Example: `"advanced_auth_api_fields": {"61": {"subfield 1": , "subfield 2": }}`' properties: '[data element number]': type: object description: Number of the data element (DE). properties: subfield 1: type: string description: Raw contents of the subfield. subfield 2: type: string description: Raw contents of the subfield. subfield N: type: string description: Raw contents of the subfield. tar_info: type: object description: 'Tokenization authorization request (TAR) data is provided by the network during mobile wallet provisioning. The following are the subfields in a tokenization authorization request. Note the distinctions between Mastercard and Visa networks. For enhanced provisioning security based on some of these fields, see Enhanced provisioning security in _Setup for Mobile Wallets_. If you do not receive this data for provisioning approved BINs, contact SoFi Tech Solutions for assistance.' properties: correlation_id: type: string description: '_Mastercard only._ Identifier assigned that can be used by the issuer to associate related tokenization requests and notification messages. 14 alphanumeric characters. Example: `"D0002688797932"`' example: D0002688797932 pan_source: type: string description: 'For Mastercard, this field identifies the method by which the cardholder is attempting to tokenize a PAN. - `1` — Card on file - `2` — Card added manually - `3` — Card added via application For Visa, this tag, if present, identifies whether it’s push provisioning. - `01` — Key entered - `02` — On file - `03` — Mobile banking application - `04` — Token - `05` — Chip dip - `06` — Contactless If the value is `03`, then it is push provisioning.' enum: - '1' - '2' - '3' - '01' - '02' - '03' - '04' - '05' - '06' payment_app_instance_id: type: string description: '_Mastercard only._ Identifier associated with the payment application instance installed onto the customer''s device. 48 alphanumeric characters. Example: `"tSnaYXYaTSkz7DoGPz_wvVLhieie4lyhMPuMrvXx4kdAwkgV"`' example: tSnaYXYaTSkz7DoGPz_wvVLhieie4lyhMPuMrvXx4kdAwkgV device_ip: type: string description: 'For Mastercard, this field is the variable-length IP address. Each octet of the IP address is converted to hex and joined into one string, with the order maintained. 8 alphanumeric characters. Example: `"83BF5B74"` For Visa, this field contains the IP address of the device at the time of the provisioning request. 15 characters maximum. Example: `"255.255.255.255"`' acc_id_hash: type: string description: '_Mastercard only._ Contains the customer’s account ID associated with the wallet provider as a PBKDF2 hash. This account ID is typically the email address. The PBKDF2 function is performed using 10 iterations, a salt, and the lowercase account ID as the password. The salt is calculated by taking the lowercase UTF-8 bytes from the account ID and performing a SHA-256 hash operation. **Example**: Input (Password): `csharp@walletprovider.com` Salt: `"41404d1bca85ddb59ab21466e277ac1ac5f61470be120c82a21b1e45b5248123"` Count: `10` Output: `"7098014b646d44c6f3b454c5d54f7a32b3b46e2b0c8e2367f3e5307e3036dfe6"`' example: 7098014b646d44c6f3b454c5d54f7a32b3b46e2b0c8e2367f3e5307e3036dfe6 cardholder_name: type: string description: '_Mastercard only._ Contains the name of the cardholder. The format is represented in one of these two formats: - LASTNAME/FIRSTNAME with the names delimited by a slash `/`. Example: `"SMITH/JOE"` - FIRSTNAME LASTNAME. Example: `"JOE SMITH"` 27 characters maximum. If the cardholder’s name is longer than 27 positions, the data is truncated.' example: SMITH/JOE tokenization_recommendation: type: integer description: 'The tokenization decision suggested by the wallet provider. For Mastercard, possible values are: - `0` — Decline - `1` — Approve - `2` — Requires additional authentication For Visa, possible values are: - `0` — Unconditionally approved - `1` — Conditionally approved with further cardholder verification - `2` — Not approved' enum: - 0 - 1 - 2 tokenization_recommendation_standard_ver: type: string description: 'The version of the standards the wallet provider is using to determine the suggested tokenization recommendation. - For Mastercard, this value is 2 digits. Example: `"01"` - For Visa, this value is a decimal value. Example: `"0002.00"`' device_score: type: integer description: 'The score assigned by the wallet provider for the device. The score is returned as a value between `1` and `5`, with `5` being most trusted. Example: `5`' enum: - 1 - 2 - 3 - 4 - 5 account_score: type: integer description: '_Mastercard only._ Score assigned by the wallet provider for the <>. Value between`1` and `5`, with `5` being most trusted. Example: `5`' enum: - 1 - 2 - 3 - 4 - 5 active_tokens: type: string description: '_Mastercard only._ Number of existing, active tokens for the PAN, excluding card-on-file tokens. Space-filled when the requested token is digitized to a server. Example: `"08"`' example: 08 tokenization_recommendation_reason_code: type: string description: 'Indicates the specific reason the wallet provider is suggesting the tokenization recommendation. For Mastercard, the data of this field is a hex-encoded bitmap, whereby each bit corresponds to a specific reason code. If the wallet provider returns no reason, this field will contain spaces. See the possible values for Visa in the Tokenization Recommendation Reason Codes. Example: `"008011"`' tokenization_recommendation_reason_codes_parsed: type: string description: '_Mastercard only._ Indicates the specific reason the wallet provider is suggesting the tokenization recommendation. This field shows the interpretation of the hex-encoded bitmap in the `tokenization_recommendation_reason_code` field for Mastercard. See the possible values for this field in the Tokenization Recommendation Reason Codes. Example: `"08" `' location: type: string description: 'Latitude and longitude points where the cardholder''s device was located at the time the tokenization was attempted. - For Mastercard. The decimal latitude and longitude values, converted to hexadecimal. Example: `"2F197A2E1"` - For Visa, when available, the latitude and longitude points are provided with up to 4 digits of precision or rounded to a less-granular level. Example: `"+39.13/-77.55"`' last_four_digits: type: string description: '_Mastercard only._ Last four digits of the cardholder''s mobile phone number associated with the active wallet. Example: `"0885"`' example: 0885 token_type: type: string description: 'The type of requested token. - `C` — Mastercard cloud-based payments - `F` — Card on file - `S` — Embedded secure element - `H` — <> cloud token' enum: - C - F - S - H consumer_identifier: type: string description: '_Mastercard only._ Unique identifier for each cardholder, which must be verified by the financial institution before a cardholder can add their credentials to the payment-enabled device. Default: blank.' device_type: type: string description: '_Visa only._ Device type value. - `00` — Unknown - `01` — Mobile phone - `02` — Tablet - `03` — Watch - `04` — Mobile phone or tablet - `05` — Personal computer' enum: - 0 - 1 - 2 - 3 - 4 - 5 device_language: type: string description: '_Visa only._ Language used by the cardholder’s device. 3 characters maximum. Example: `"eng"` for English.' example: eng device_id: type: string description: '_Visa only._ The device ID. 48 characters maximum. Example: `"MTgwOTIxMTQzMjAwMTA0LUh0"`' example: MTgwOTIxMTQzMjAwMTA0LUh0 device_number: type: string description: '_Visa only._ Contains the device number, or the full or partial telephone number, when available. Provided by the Visa network. Example: `"15127717396"`' example: '15127717396' device_name: type: string description: '_Visa only._ The name of the device given by the cardholder. 16 characters maximum. Value is truncated when longer than maximum length. Example: `"Work Phone"`' example: Work Phone account_id: type: string description: '_Visa only._ Contains the wallet account ID. Example: `"eg2t6TyJQ2G8NIraaCypzg"`' example: eg2t6TyJQ2G8NIraaCypzg account_email_addr: type: string description: '_Visa only._ Contains the hashed full email address for the cardholder account that was sent by the wallet provider. Example: `"\xc1_\xf8\xc8_/\xd1%%\x06\xc4?_"`' example: Á_øÈ_/Ñ%%Ä?_ visa_token_score: type: string description: '_Visa only._ Contains the Visa Token Score associated with a token. Scores range from 01-99, with higher values indicating higher risk. `00` indicates a token was not scored. Example: `"01"`' example: '01' required: - correlation_id - pan_source - payment_app_instance_id - device_ip - acc_id_hash - cardholder_name - tokenization_recommendation - tokenization_recommendation_standard_ver - device_score - account_score - active_tokens - location - last_four_digits - token_type - consumer_identifier - device_id fleet_info: type: object description: Information that is provided for cards with fleet-card BINs, which are Mastercard only. See Fleet Cards for more information. properties: fleet_card_driver_number: type: integer description: 'Driver ID. 17 digits maximum. Example: `06123456`' fleet_card_vehicle_number: type: integer description: 'Vehicle ID. 17 digits maximum. Example: `03123`' fleet_prompt_data: type: integer description: 'Contains occurrences of the prompt code read from a card chip. There can be up to 5 prompt codes. Consult the documentation from Mastercard for the full list. Example: `002` (vehicle number)' merchant_override_indicator: type: integer description: 'Indicates if the merchant point-of-sale supports the fleet spend control override capability: `0` (does not support) or `1` (supports)' control_override_items: type: integer description: Provides merchants with information, on a transaction basis, to override purchase restrictions to allow products to be purchased that may not have otherwise been allowed. Only to be populated when DE106SE2 contains the value `1`, indicating that the merchant point-of-sale supports the fleet spend-control override capability. fuel_info: type: integer description: 'Contains item-level detail information of the motor fuel product(s) purchased at the POS (3 digit code). Can have up to 3 subfields. Consult the documentation from Mastercard for the full list. Example: `036` (racing fuel)' non_fuel_info: type: integer description: 'Contains item-level detail information of the non-fuel product(s) purchased at the POS. Can have up to 12 subfields. Consult the documentation from Mastercard for the full list. Example: `102` (car wash)' aifi_fields: type: object description: _Colombia only_. Information related to ATM issuer-fee inquiries. properties: issuer_fee_inquiry_indicator: type: string description: Contains `"01"` to indicate issuer-fee inquiry request. DE112SE035. pos_transaction_status: type: integer description: Contains `"8"` to indicate account-status inquiry (ASI) service. DE061SF7. issuer_fee_amt: type: string default: '0.0' description: 'Amount of the ATD (domestic ATM) fee. This amount is displayed to the cardholder as the issuer fee. DE112SE036. Example: `"15000.00"`' merchant_advice_code: type: - string - 'null' description: '_Mastercard only._ Contains the supported merchant advice code (MAC), if applicable: `03`, `40`, `41`, or `43`. The GMACD parameter must be set to `Y` to enable MAC decisioning.' example: '40' fraud_results: type: object description: _Mastercard only_. Contains the results from the Mastercard Fraud Rule Management Service. If you subscribe to this service, ask SoFi Tech Solutions to enable this object. Consult the documentation from Mastercard for DE048SE56 to interpret the values. properties: AQV: type: string description: 'GDV-based spend ranking. Example: `"400"`' example: '400' AQF: type: string description: 'Frequency-based spend ranking. Example: `"100"`' example: '100' AQS: type: string description: 'Segment qualifier. Example: `"002"`' example: '002' AIQ: type: string description: 'Digital transaction insights. Example: `"3QZ"`' example: 3QZ required: - AQV - AQF - AQS - AIQ fraud_scoring_data: type: object description: '_Mastercard only._ DE048SE75. Contains the results from Mastercard''s Expert Monitoring, Fraud Scoring Service, or Decision Intelligence (DI) service. If you subscribe to any of these services, ask SoFi Tech Solutions to enable this object. Consult the documentation from Mastercard for your service to interpret the values. ' properties: risk_assessment_score: type: integer description: 'Mastercard Decision Intelligence (DI) score ranging from `0-999`. Example: `"089"`' example: '89' risk_assessment_score_reason_code: type: string description: 'Fraud reason code. Indicates the key factors that influenced the value in `risk_assessment_score`. Example: `"64"`' example: '64' real_time_fraud_score: type: string description: 'The Fraud Rule Manager Service provides the rule-adjusted score of `000-999`, where `000` indicates the least likely fraudulent transaction and `999` indicates the most likely fraudulent transaction. Example: `"089"`' example: 089 real_time_fraud_score_reason_code_1: type: string description: 'An alphanumeric reason code that identifies the data used to derive the `real_time_fraud_score`. Example: `"64"`' example: '64' real_time_fraud_score_reason_code_2: type: string description: 'An alphanumeric reason code that identifies the data used to derive the `real_time_fraud_score`. Example: `"00"`' example: '00' digital_payment_data: type: object description: '_Mastercard only._ DE104SE4. Contains the results from Mastercard''s Token Authentication Framework (TAF) program. If you subscribe to Mastercard''s Expert Monitoring, Fraud Scoring Service, or Decision Intelligence (DI) service, ask SoFi Tech Solutions to enable this object to use for decisioning. Consult the documentation from Mastercard on DE104 Subelement 004 to interpret the values. ' properties: digital_service_provider: type: string description: 'Identifies the entity that authenticated the transaction. Consult the documentation from Mastercard for a complete list of values for DE104SE4SF1. Example: `"001005A0010"`' example: 001005A0010 digital_authentication_data: type: string description: 'Confirms that the transaction was fully authenticated, and identifies the authentication method used. Consult the documentation from Mastercard for a complete list of values for DE104SE5SF1. Example:`"0010054TRID00200500000"`' example: 0010054TRID00200500000 latest_incremental_id: type: integer description: 'The `auth_id` of the previous authorization in an incremental sequence when `incremental_auth: true`. This field contains the same information as `original_id` and is present only by request. Example: `13371854`' example: 13371854 original_incremental_id: type: integer description: 'The `auth_id` of the first authorization in an incremental sequence when `incremental_auth: true`. This field is present only by request. Example: `13369203`' example: 13369203 account_attack_intelligence_score: type: - string - 'null' description: '_Visa only_. A score for <> transactions to evaluate risk of enumeration attacks. Field 104, Dataset 5B, Tag 85. Valid values are `01-99` or null. Lower scores mean less risk. Example: `"24"`' example: 24 relay_resistance_protocol_data: type: object description: _Mastercard only_. DE048SE71. For tokenized (mobile wallet), contactless transactions, this is information captured at the terminal related to the possibility of relay attacks. For valid values, see Relay Resistance Protocol Data. properties: on_behalf_service: type: string description: 'The type of service performed on the transaction. Example: `"51"`' example: '51' result_1: type: string description: 'The first result from the on-behalf service. Example: `"A"`' example: A result_2: type: string description: 'The second result from the on-behalf service, if any. Example: `"K"`' example: K service_processing_type: type: - string - 'null' description: '_Visa only_. Service processing type for scheduled, deferred <>s. See Service Processing Types for valid values. Field 104 Dataset 57 Tag 80. Example: `"03"`' example: '03' visa_atm_managed_services: type: object description: _Visa only_. Managed-service information. Field 111 Dataset 02. properties: managed_service_indicator: type: string description: 'Whether this is a managed-service transaction. Tag 82. Example: `"Y"`' example: Y agreement_type: type: string description: 'The type of managed service that was provided for this transaction. Consult the documentation from Visa for valid values. Tag C1. Max 4 char. Example: `"1234"`' example: '1234' is_in_person_tap_transaction: type: boolean description: _Visa only_. Whether this is a direct in-person tap transaction. Applies only to <>s and <>s. Field 34. example: true vdcap_info: type: object description: _Visa only_. <> information from Field 34, Field 56, and Field 111. properties: authentication_program: type: string description: 'Indicates which authentication solution or data-sharing solution was used to process the transaction. See VDCAP Info for valid values. Field 34 Dataset 01 Tag C0. Example: `"01"`' example: '01' consumer_device_ip_address: type: string description: 'External IP address that is the device public IP address used by the 3DS requestor application when it connects to the 3DS requestor environment. Field 34 Dataset 01 Tag 92. Example: `"172.16.22.52"`' example: 172.16.22.52 applied_special_service: type: string description: 'Indicates whether the merchant has used the eligible authentication or data-sharing method and provided the required data elements. Visa sends `1` (<>) if all the conditions are met. Field 111 Dataset 56 Tag 89. Example: `"1"`' example: '1' other_phone_number: type: string description: 'A phone number belonging to the cardholder. Field 56 Dataset 02 Tag 83. Max 16 char. Example: `"8015552333"`' example: '8015552333' browser_ip_address: type: string description: '3DS browser IP address. Field 34 Dataset 01 Tag 89. Example `"10.0.45.66"`' example: 10.0.45.66 other_email_address: type: string description: 'An email address belonging to the cardholder. Field 56 Dataset 02 Tag 86. Max 99 char. Example: `"3dsuser@exampledomain.com"`' example: 3dsuser@exampledomain.com device_id: type: string description: 'Unique identifier associated with the cardholder device. Field 34 Dataset 06 Tag 86. Max 64 char. Example: `"device000"`' example: device000 credit_info: type: object description: Contains information related to credit accounts. properties: credit_card_balance: type: number description: 'The outstanding balance on a credit account. This value can be interpreted as being accurate as of the `opentobuy_ts`. Example: "-249.51"' example: '-249.51' opentobuy_ts: type: string description: 'Date and time when when the `credit_card_balance` was last captured. Format is YYYY-MM-DD hh:mm:ss.ssssss and timezone is always `MST`, which is Arizona time (GMT -0700). Example: `"2025-03-17 14:06:50.243654"`' example: '2025-03-17 14:06:50.243654' mastercard_transaction_id_data: type: object description: _Mastercard only_. Derived from DE105, Multi-Use Transaction Identification Data. Contains the <>, which is globally unique in a distributed environment and used as a single unique reference to perform matching and linking of all message activity properties: tlid: type: string description: 'DE105SE1. Transaction link identifier. A unique ID that Mastercard generates for each original transaction. Example: `"aabb112233445566"`' example: aabb112233445566 economically_related_tlid: type: string description: DE105SE2. The Mastercard-generated TLID from an economically related independent transaction that a customer retains and returns in subsequent economically related transactions. example: ff00ee11dd22cc33 lifecycle_tlid_validation_data: type: object description: Data relative to the TLID lifecycle. properties: action_indicator: type: string description: 'DE105SE3SF1. Indicates whether Mastercard modified the `tlid`, either because the customer did not provide a TLID in a lifecycle-linking scenario, or the TLID was unmatched. Possible values: - `1` — Mastercard populated `tlid` with the original message TLID. The customer did not submit a lifecycle message with a TLID, and so `customer_provided_tlid` will not be populated. - `2` — Mastercard populated `tlid` with the original lifecycle message TLID. The customer submitted the lifecycle message with a TLID value that did not match the original message. Mastercard moved the customer-provided TLID value to `customer_provided_tlid`. - `3` — Mastercard generated a new TLID value for `tlid`. Mastercard was unable to match this lifecycle message to any original message. If the customer submitted this transaction with a TLID value, Mastercard moved the customer-provided TLID value to `customer_provided_tlid`.' example: '2' customer_provided_tlid: type: string description: DE105SE3SF2. Contains the customer-provided TLID value from DE105SE1 (`tlid`) when Mastercard is unable to confirm the validity of that customer-provided TLID value. example: cc998877dd665544 required: - auth_type - transaction_type - id - timestamp - network - subnetwork - account - amounts - mcc - merchant - mti - transaction - validation_results - international - response_code - auth_id - partial_supported - entry_type - response_code_list - ecommerce - eligible_for_balance_return - emv - version responses: '200': description: 'Use the fields in this schema to respond with your decision plus any instructions for SoFi Tech Solutions. ' content: application/json: schema: type: object properties: response_code: type: string description: 'Authorization response code, which specifies whether a transaction is approved or denied. See the Authorization Response Codes enumeration for possible values. Example: `"05"`' example: '05' avs_response: type: string description: 'Use this field to override `avs_result`, if you believe `avs_result` is wrong. See AVS Codes for valid values. Example: `"Y"`' override_limit: type: boolean description: 'Use this field to override authorization limits, if permitted. If this field is `true` then any limits that would be reached are overridden. Example: `true`' example: true partial_amount: type: number format: float minimum: 0 description: 'If `response_code` indicates a partial approval (`10` or `87`), this is the partial amount to approve. Example: `5.00`' example: 5 transfer_prn: type: string minLength: 12 maxLength: 12 description: 'If you want to perform a transfer to cover a lack of funds, this is the PRN of the account to supply the funds. Example: `"155200002717"`' example: '155200002717' transfer_amount: type: number format: float minimum: 0 description: 'The amount to transfer from the `transfer_prn` to the cardholder account. Example: `20.00`' example: 20 source_transfer_type: type: string description: 'The transaction type for the adjustment on the source account in `transfer_prn`. Use the value that SoFi Tech Solutions supplied. Case sensitive. Default: `pc`. Example: `"lm"`' minLength: 2 maxLength: 2 example: pc dest_transfer_type: type: string description: 'The transaction type for the adjustment to the cardholder account. Use the value that SoFi Tech Solutions supplied. Case sensitive. Default: `PC` Example: `"LM"`' minLength: 2 maxLength: 2 example: PC available_balance: type: number format: float description: 'If `eligible_for_balance_return: true` AND you hold the ledger for the card account, populate this field with the card account''s available balance to spend _before_ the transaction is performed. Otherwise, SoFi Tech Solutions sends the balance it has in the response message. The amount should be in the account currency. (The card networks will perform currency conversion as needed.) Example: `250.00`' example: 250 savings_balance: type: number format: float description: 'If `eligible_for_balance_return: true` AND you hold the ledger for the cardholder''s savings account, populate this field with the savings account balance in the currency of the account. Otherwise, SoFi Tech Solutions sends the balance it has in the response message. Example: `4000.00`' example: 4000 available_credit: type: number format: float description: 'If `eligible_for_balance_return: true` AND you hold the ledger for the cardholder''s credit account, populate this field with the credit limit remaining in the currency of the account. Otherwise, SoFi Tech Solutions sends the remaining limit it has in the response message. Example: `1500.00`' example: 1500 merchant_advice_code: type: string description: '*Mastercard only.* Use this field to override MAC decisioning, if permitted. Leave blank if you do not wish to override the SoFi Tech Solutions MAC decision. SoFi Tech Solutions reverts to the original decision if an invalid MAC is provided. The MACO product parameter must be set to `Y` to enable overrides.' example: '41' required: - response_code examples: Approve Transaction: summary: Approve transaction value: response_code: '00' Override avs_result: summary: Override AVS result value: response_code: '00' avs_response: Y Transfer: summary: Real-time transfer value: response_code: '00' transfer_prn: '155200002717' transfer_amount: 20 source_transfer_type: pc dest_transfer_type: PC available_balance: 250 Do Not Honor: summary: Override approval value: response_code: '05' Return Multiple Balances: summary: Return multiple balances value: response_code: '00' available_balance: 3654.22 savings_balance: 2450.89 available_credit: 354.34 /base_path/Authorization: post: summary: Auth API Webhook 3.0 description: 'With the Auth API 3.0 webhook, you can participate in authorization decisions. For this webhook there is only one verb: `POST`. SoFi Tech Solutions sends information about the authorization request in the body of the HTTP request, in JSON. Your decision should be in the body of the HTTP response. In the authorization information that we send, the `response_code` is the current response code to be returned to the merchant, unless you override it. Use the `response_code` field in the HTTP response body to override the authorization response code, as desired. See the Authorization Controller API guide for more information. > 📘 About the field properties > > SoFi Tech Solutions initializes the webhook payload by setting all fields to `null`. As values come in with the ISO 8583 authorization request, we populate the respective payload fields with the data the network sends, which can include empty strings (`" "`). This documentation shows the field properties (data type, nullability, required) that are most likely. However, variations by network and transaction type mean that a few of the values passed in the webhook payload can vary from what is shown here. Open the Recipes below to see webhook examples that you can use for testing.' operationId: webhook_authorization_post_3 tags: - Auth API Webhook parameters: - name: X-Request-ID in: header description: A unique identifier for the HTTP request. schema: type: string format: uuid required: true requestBody: description: Information about the authorization request. required: true content: application/json: schema: type: object properties: auth_type: type: string description: 'All transactions are grouped into three basic message types: * `Auth` — Authorization request. MTI x1xx (authorization or preauthorization over credit rails or preauthorization over debit rails) or x2xx (authorization over debit rails). * `Advice` — Notification of a completed transaction. MTI xx2x. Only a `00` response code is permitted. * `Reversal` — A reversal of a previous authorization. MTI x4xx. May or may not reference the previous authorization.' enum: - Auth - Advice - Reversal transaction_type: type: string description: 'The transaction type indicates at a lower level what kind of transaction this is. This field is used to differentiate merchant credits, ATMs, balance inquiries, etc. * `Preauth` — A preauthorization for an estimated amount. Often followed by a completion advice. * `Auth` — Conventional authorization request. Also used with advices and reversals. * `ATM` — ATM withdrawal. * `Cash Advance` — Cash advance from a teller. * `Balance Inquiry` — Balance inquiry from an ATM. * `Merchant Credit` — A credited amount from a merchant. Usually does not reference a previous authorization. * `Adjustment` — Debit adjustment, unrelated to a previous authorization. The merchant is adjusting a cardholder balance. * `Payment` — Loading funds onto a card. * `Tokenization` — A request to tokenize a card for use in a mobile wallet or a request from a merchant to validate a tokenized card for payment.' enum: - Preauth - Auth - ATM - Cash Advance - Balance Inquiry - Merchant Credit - Adjustment - Payment - Tokenization id: type: string description: "Unique identifier for this authorization. \n\nExample: `\"DHWJtI8zRjuDcgF8hru3oQ\"`" example: DHWJtI8zRjuDcgF8hru3oQ timestamp: type: string description: 'Date and time when the webhook was sent by SoFi Tech Solutions. Format is ``, where `timestamp` is `YYYYMMDD:HHMMSS` and `timezone` is always `MST`, which is Arizona time (GMT -0700). Example: `"20250315:121504MST"`' example: 20250315:121504MST network: type: string description: 'Card network name. Possible values: * `Visa` * `Allpoint` * `Discover` * `Mastercard` * `Star` * `Pulse`' enum: - Visa - Allpoint - Discover - Mastercard - Star - Pulse subnetwork: type: string description: 'The subnetwork name. This is the same as `network` if there is no subnetwork. Possible values: * `Visa` * `Visa Interlink` * `Visa PLUS` * `Mastercard Banknet` * `Mastercard Debit Switch` * `Discover` * `Allpoint` * `Star` * `Star MoneyPass` * `Star Presto` * `Pulse`' enum: - Visa - Visa Interlink - Visa PLUS - Mastercard Banknet - Mastercard Debit Switch - Discover - Allpoint - Star - Star MoneyPass - Star Presto - Pulse account: type: object properties: xid: type: integer description: 'Internal ID for the account. Example: `5398373`' example: 5398373 cad: type: integer description: 'System-generated ID for the card. This ID has a 1:1 relationship with the <>. Example: `72450868`' example: 72450868 prn: type: string minLength: 12 maxLength: 12 description: 'Payment reference number for the account. 12 digits. Example: `"999200002022"`' example: '999200002022' product_id: type: - integer - 'null' description: 'Product ID for the account, as provided by SoFi Tech Solutions. Example: `2577`' example: 2577 program_id: type: - integer - 'null' description: 'Program ID for the account, as provided by SoFi Tech Solutions. Example: `566`' example: 566 pan: type: string description: 'Last four digits of the <> of the card. Example: `"5198"`' example: '5198' account_status: type: string description: 'Account status code. See the possible values in the Account Statuses enumeration. Example: `"N"`' card_status: type: string example: N description: 'Card status code. See the possible values in the Card Statuses enumeration. Example: `"N"`' expiration_date: type: string minLength: 4 maxLength: 4 description: 'Card expiration date (format `YYMM`). Example: `"2103"`.' example: '2103' track_expiration_date: type: - string - 'null' minLength: 4 maxLength: 4 description: 'The expiration date (format: `YYMM`) that was read from the card''s magnetic stripe and sent in the ISO message, if present and applicable. For example, this field will not be present for a card-not-present transaction. Example: `"2103"`' example: '2103' merchant_supplied_expiration_date: type: - string - 'null' minLength: 4 maxLength: 4 description: 'The expiration date (format: `YYMM`) supplied by the merchant, if present and applicable. Example: `"2103"`' example: '2103' required: - xid - cad - prn - pan - account_status - card_status - expiration_date - track_expiration_date - merchant_supplied_expiration_date amounts: type: object description: 'The amounts are always unsigned. To calculate the sign for an amount, start with a factor of –1, and then apply another factor of –1 for each of the following criteria: * `"auth_type": "Reversal"` * `"transaction_type": "Merchant Credit"` * `"transaction_type": "Payment"` Amount fields may not display a numeric value for non-active cards. Instead, the string `"none"` could be displayed.' properties: currency: type: - string - 'null' minLength: 3 maxLength: 3 description: 'The currency code for the amounts, unless otherwise indicated. This is the currency of the cardholder account. ISO 4217 Numeric Currency Code. 3 digits. Example: `"840"`' example: '840' trans_amount: type: string description: 'Transaction amount. Full amount of the authorization request, including upcharges and fees and after any currency conversion is performed. Example: `"12.40"`' example: '12.40' partial_amount: type: string default: '0.0' description: 'If `partial_supported: true` and `response_code` is `10` or `87`, this is the amount of the partial approval. Example: `"10.00"`' example: '10.00' cashback_amount: type: string default: '0.0' description: 'Cashback amount requested. This amount is included in `trans_amount`. Example: `"5.00"`' example: '5.00' fee_amount: type: string default: '0.0' description: 'Amount of any fees. This amount is included in `trans_amount`. Example: `"1.50"`' example: '1.50' available_funds: type: string description: 'The card''s available balance before this transaction is applied. If this authorization request is approved, the card''s available balance is affected within a few milliseconds after the approval is sent to the network. Keep in mind that this is the available balance known to SoFi Tech Solutions—if you are the system of record for your program, refer to your records to determine whether the account has sufficient funds. Example: `100.00`' example: 100 amt_til_limit: type: string default: '0.0' description: 'Amount remaining before `nearest_limit` is reached. Example: `502.80`' example: 502.8 nearest_limit: type: - string - 'null' description: 'The name of the first limit that would be reached if a partial authorization or denied authorization is overridden via the `override_limit` field. This field is present only when the limit would be reached in overriding the authorization. Example: `"PCL Daily Limit"`' example: PCL Daily Limit local_currency: type: string minLength: 3 maxLength: 3 description: 'ISO 4217 numeric currency code for `local_currency_amount`, which is the currency at the point of sale. 3 digits. Example: `"124"`' example: '124' local_currency_amount: type: string default: '0.0' description: 'Amount of the request in the currency at the point of sale. Upcharges and fees are not included. Example: `"21.00"`' example: '21.00' settle_currency: type: - string - 'null' minLength: 3 maxLength: 3 description: 'ISO 4217 numeric currency code for `settlement_currency_amount`. To understand what a settlement currency is, see Multicurrency BINs. 3 digits. Example: `"978"`' example: '978' settle_currency_amount: type: string default: '0.0' description: 'Amount of the request in the settlement currency. Upcharges and fees are not included. Example: `"17.00"`' example: '17.00' billing_currency: type: string minLength: 3 maxLength: 3 description: 'ISO 4217 numeric currency code for `billing_currency_amount`. Example: `840`' example: 840 billing_currency_amount: type: string default: '0.0' description: 'The amount of the transaction in the billing currency, which is the currency of the card account. Example: `"12.40"`' example: '12.40' local_surcharge_amt: type: string default: '0.0' description: 'The surcharge amount in the currency at the point of sale. Example: `"0.50"`' example: '0.50' settle_surcharge_amt: type: string default: '0.0' description: 'The surcharge amount in the settlement currency. Example: `"0.75"`' example: '0.75' settle_exchange_rate: type: string description: 'The factor used to convert from the local request amount to the settlement amount. The string has the pattern ``. The first digit specifies how many places from the right the decimal is moved. For example, `69985022` translates to an exchange rate of 9.985022%. Example: `"69985022"`' example: '69985022' exchange_rate: type: string description: 'The factor used to convert from the local request amount to the billing amount. The string has the pattern ``. The first digit specifies how many places from the right the decimal is moved. For example, `69985022` translates to an exchange rate of 9.985022%. Example: `"65991234"`' example: '65991234' upcharge_amount: type: string default: '0.0' description: 'The upcharge amount, which is included in `trans_amount`. Example: `"75.00"`' example: '75.00' required: - currency - trans_amount - cashback_amount - fee_amount - available_funds - amt_til_limit - upcharge_amount mcc: type: integer description: 'Merchant category code. This value does not include leading zeros. Example: `5992`' example: 5992 digital_commerce_data: type: object description: '_Mastercard only_. Contains data regarding a digital commerce transaction. Derived from DE048SE48. See Digital Commerce Solutions Indicators for more information. ' properties: entity_type_name: type: string description: 'SF3. The check-in entity type and entity name. Example: `"202010030220"` ' example: '202010030220' domain_id: type: string description: 'SF1. The entity responsible for populating the other fields in this object. Example: `"01"` ' example: '01' program_id: type: string description: "SF2. The specific digital commerce program.\n \n\nExample: `\"01\"`\n" example: '01' checkin_method: type: string description: 'SF4. The methods that a check-in entity applies to validate cardholder presence. **Required** when `program_id: 04`. Example: `" "` ' example: null merchant: type: object properties: acquirer_id: type: - string - 'null' description: 'The acquiring institution ID. Example: `"406160"`' example: '406160' terminal_id: type: - string - 'null' description: 'The ID for the device that acquired the card information. Example: `"A1Z23B99"`' example: A1Z23B99 merchant_id: type: - string - 'null' description: 'The merchant ID, as assigned by the network. Example: `"39AJKEO30634KVN3"`' example: 39AJKEO30634KVN3 merchant_description: type: - string - 'null' description: 'The merchant description. Example: `"123 WIDGETS MERCHANT BEVERLY HILLS CA"`' example: 123 WIDGETS MERCHANT BEVERLY HILLSCA merchant_country: type: - string - 'null' description: 'ISO 3166-1 country code for the country where the merchant is located. 3 digits. Example: `"840"`' example: '840' merchant_postal_code: type: - string - 'null' description: 'Postal code, nine characters. Left-justified and padded with zeros. If there are nine zeros, then no postal code was provided. Example: `"902100000"`' example: '90210' merchant_state: type: - string - 'null' description: 'Two-letter state or provincial designator for the merchant''s location. Example: `"NV"`' example: NV terminal_network: type: - string - 'null' description: 'Network to which the terminal belongs, Possible values are `VPA` (Visa PLUS Alliance), `Allpoint`, or `None` (another network). If you are not configured to receive this data, the value will always be `None`. Example: `"VPA"`' example: VPA enum: - Allpoint - VPA - None required: - acquirer_id - terminal_id - merchant_id - merchant_description - merchant_country - merchant_postal_code - merchant_state - terminal_network mti: type: string description: 'Message-type indicator, as defined by ISO 8583. See Message types in the _Authorization Controller API_ guide. Example: `"0200"`' example: '0200' transaction: type: object description: Information about the transaction properties: recurring: type: string description: 'Whether a transaction is recurring: `Y` or `N`. Example: `"N"`' example: N cardholder_present: type: string description: 'Whether the physical card was present at the point of sale: `Y` or `N`. Example: `"Y"`' example: Y transaction_initiator_code: type: string description: '*Mastercard only.* Whether the transaction was initiated by the cardholder or the merchant. Populated only when DE048 subfield 22 is present in the authorization request. See CIT and MIT Indicators for more information. Example: `"M101"`' example: M101 is_advance_payment: type: boolean description: _Visa only_. Field 126 SE 13. Whether the transaction is an advance payment, meaning that the merchant secures the payment before the goods or services are available. example: true required: - recurring - cardholder_present validation_results: type: object properties: cvv1: type: string description: 'Result of <>1 validation. Possible values: * `Y` — Validated * `F` — Failed * `N` — Not present' enum: - Y - F - N cvv2: type: string description: 'Result of CVV2 validation. Possible values: * `Y` — Validated * `F` — Failed * `N` — Not present' enum: - Y - F - N cvv3: type: string description: 'Result of CVV3 validation. Possible values: * `Y` — Validated * `F` — Failed * `N` — Not present' enum: - Y - F - N pin: type: string description: 'Result of PIN validation. Possible values: * `Y` — Verified * `F` — Failed * `L` — Locked * `M` — PIN not set * `B` — Blocked * `N` — No PIN was passed' enum: - Y - F - L - M - B - N arqc: type: string description: 'Result of validating the authorization request cryptogram for an EMV chip. Possible values: * `Y` — Validated * `F` — Failed * `N` — Not present' enum: - Y - F - N offline_pin: type: string description: 'Result of validating the offline PIN. Possible values: * `Y` — Validated * `F` — Failed * `N` — Not present * `E` — Offline PIN attempts exceeded * `P` — Ignored due to risk params' enum: - Y - F - N - E - P avs_result: type: string description: 'Result of the <> check. See AVS Codes for valid values. Example: `"Y"`' enum: - Y - A - Z - N - M - T - X - S - U - B - C - D - R aav: type: string description: 'Result of validating the <>/<>. Possible values: * `Y` — Validated * `F` — Failed * `N` — Not present' enum: - Y - F - N required: - cvv1 - cvv2 - cvv3 - pin - arqc - offline_pin - avs_result - aav avs_data: type: object description: When the authorization includes an <> request, this object contains the data that SoFi Tech Solutions used to calculate the AVS response. properties: zip: type: string description: 'Postal code provided by the cardholder. Example: `"84121"`' example: '84121' address: type: string description: 'Numbers in the first address line, provided by the cardholder. Example: `"1235"`' example: '1235' required: - zip - address international: type: boolean description: 'Whether this is an international transaction. ' example: true response_code: type: string description: 'Authorization response code, which specifies whether a transaction is approved or denied. See the Authorization Response Codes enumeration for possible values. Example: `"05"`' example: '05' auth_id: type: integer description: 'System-generated ID for the authorization. Use this ID to track the transaction throughout the system. For an explanation of how these IDs are generated, see Authorization identifiers in the _Transaction IDs_ guide. Example: `13371854`' example: 13371854 partial_supported: type: boolean description: Whether the merchant supports partial authorizations. example: true stip: type: object description: This object is present when a <> transaction is processed by the network. See Stand-in processing in the _Authorization Controller API_ guide for more information. properties: detail: type: string description: 'Advice reason code relayed from the network, which provides information on the STIP transaction. See Advice Reason Codes for valid values. Example: `"4000000"` or `"9020"`' example: '9020' stip_decision: type: string description: 'The Authorization Response Code that was returned to the merchant by the STIP process. Example: `"00"`' additional_detail: type: - string - 'null' description: 'More information about the STIP transaction. See STIP Additional Detail for valid values. Example: `"000003"`' is_stip_denial: type: string description: 'Whether the transaction was denied by the STIP process: `N` (approved). Denied STIP transactions do not trigger an Auth API message. Example: `"N"`' incremental_auth: type: boolean description: 'If this authorization is part of an an incremental sequence, this field is `true` and `original_id` contains the `auth_id` of the previous authorization in the sequence. ' example: true entry_type: type: string description: 'Method of entering the <>, also known as <> entry mode. See DE022 Codes to correlate with the numerical values. Possible values: * `Card Not Present` — Online, mail order or telephone order * `Card On File` — _Mastercard only._ Card number is kept on file * `E-Commerce` — _Mastercard only._ The card was used on an ecommerce site * `EMV Chip` — The card has an EMV chip that was inserted in an EMV slot * `EMV Contactless` — Contactless transaction with EMV chip card * `EMV Fallback` — Unable to use the EMV chip: fallback to magstripe * `Magnetic Stripe` — The magnetic stripe was read * `Contactless` — Contactless transaction with magstripe card * `Manual` — Manually entered information * `Other` — None of the above' enum: - EMV Chip - EMV Contactless - EMV Fallback - Magnetic Stripe - Contactless - Card Not Present - Manual - Other pin_entry_capability: type: string description: 'Condition of the PIN pad at the point of sale. See DE022 Codes to correlate with the numerical values. Possible values: * `Capable` — Terminal has PIN-entry capability * `Incapable` — Terminal has no PIN-entry capability * `Inoperative` — Terminal has PIN-entry capability but it is not working * `Other` — Unknown PIN-entry capability, or not applicable.' enum: - Capable - Incapable - Inoperative - Other payment_info: type: object description: When `transaction_type` is `Payment`, the name of the sender and fund source, if provided in the request. properties: sender_name: type: - string - 'null' description: 'Name of the sender of the payment. Example: `"John Doe"`.' example: John Doe fund_source: type: - string - 'null' description: 'Source of the payment. Example: `"Visa Prepaid"`.' example: Visa Prepaid original_id: type: integer description: 'The `auth_id` of a previous authorization that is linked to this authorization. For reversals or completions, this is the `auth_id` of the authorization that is being reversed or completed. For incremental sequences, this is the `auth_id` of the previous authorization in the sequence. Example: `13663253`' example: 13663253 risk_score: type: string description: 'The risk score provided by the network. Mastercard range: 0–999, Visa range: 01–99. Higher values indicate higher risk. Product settings determine whether the threshold was exceeded. Example: `"23"`' example: '23' token_type: type: - string - 'null' description: 'If this is a tokenized transaction, its type. Possible values: * `Apple Inc` * `Google Inc.` * `Masterpass` * `Merchant` * `Microsoft` * `Samsung Corporation` * `Visa Checkout`' enum: - Apple Inc. - Google Inc. - Masterpass - Merchant - Microsoft - Samsung Corporation - Visa Checkout rules_denied: type: array description: 'Valid only when using our fraud-rules engine. List of fraud rules that caused a decline. Set the RULAP product parameter to receive these rules. Example: `["hr_crypto:DENY", "intl_cnp_ecom:DENY"]`' items: type: string rules_warned: type: array description: 'Valid only when using our fraud-rules engine. List of fraud rules that caused a warning. Set the RULAP product parameter to receive these rules. Example: `["dom_cp:WARN"]`' items: type: string response_code_objects: type: object description: "An object containing response codes that SoFi Tech Solutions has calculated, with a textual explanation of the response code. Consult Response Code Object Messages for possible values.\nExample:\n```json\n{\n \"75\": [\n \"PIN retry count limit reached\"\n ],\n \"57\": [\n \"Card is frozen\",\n \"Load transactions not allowed\"\n ]\n}\n```\n" bai: type: string description: 'Business application identifier. _Visa only._ See the Business Application Identifier enumeration for possible values. Example: `"FD"`' example: FD risk_code: type: string description: '_Mastercard only_. Fraud reason code. Indicates the key factors that influenced the value in `risk_score`. Example: `"58"`' ecommerce: type: object description: This object contains information related to <> authentication, if the website supported 3DS. Included in this information is the result of validating the <> for Mastercard or the <> for Visa. For detailed information about these fields, refer to The ecommerce object in the _3-D Secure Access Control Server_ guide. properties: is_ecommerce: type: - boolean - 'null' description: Whether the transaction took place on a website that supports 3DS. example: true raw_eci: type: string description: 'The electronic commerce indicator (ECI) that is sent in the authorization request. Example: `"212"`' example: 212 aav_indicator: type: string description: 'Universal Cardholder Authentication Field (UCAF). Example: `"kE"`' example: kE merchant_asserts_data_protection: type: - boolean - 'null' description: Whether the merchant or acquirer claims that the connection between the ecommerce site and the cardholder was encrypted. example: true merchant_asserts_authentication_attempted: type: - boolean - 'null' description: Whether the merchant or acquirer claims that 3DS authentication was attempted. example: None merchant_asserts_authenticated: type: - boolean - 'null' description: Whether the merchant or acquirer claims that the 3DS authentication was successful. example: false merchant_authentication_assertions_validated: type: - boolean - 'null' description: Validation results of the merchant's assertions. example: true cavv_result_code: type: - string - 'null' description: '_Visa only_. A code that indicates the outcome of CAVV validation. See CAVV Result Code for valid values. Example: `"B"`' example: B required: - is_ecommerce eligible_for_balance_return: type: boolean description: 'Whether the cardholder''s balance can be returned. This field is always `true` when `transaction_type: Balance Inquiry`. See Balance-inquiry responses in the _Authorization Controller API_ guide for information on returning balances in the response to this message.' example: true emv: type: object description: Additional EMV information. Also see EMV entry types under `entry_type` and EMV-related fields under `validation_results`. properties: is_emv: type: boolean description: This field is `true` if the `entry_type` is `EMV Chip` or `EMV Contactless`. When this value is `true`, the remaining fields below will be present, although they may be only partially populated, depending on the card network or EMV entry type. example: true brand: type: string description: 'Type of EMV. Possible values: * `visa` * `mastercard` * `discover` The card network may not match the EMV brand. For example, Visa EMV technology can be used on a card whose BIN is serviced through Allpoint.' example: visa enum: - visa - mastercard - discover terminal_verification_results: type: object description: 'This object interprets the status bits sent by the payment terminal, based on what happened during the transaction, such as whether the cardholder entered a valid PIN. Selected bits of the TVR have been separated out into the Boolean fields below. Use these fields with caution: There can be inconsistencies between different networks, and some bits are not applicable for certain entry types such as `EMV Contactless`. For example, Discover states that byte 3, bits 4 and 5 should be ignored for contactless transactions.' properties: raw: type: - string - 'null' description: 'The raw TVR (as a hex string) that was received in the ISO 8583 message, if present. If not present this field is null and the remaining fields in the `terminal_verification_results` object will not be present. Example: `"0000000000"`' online_pin_entered: type: boolean description: '_Byte 3, bit 3._ Whether a PIN is being sent in the ISO message for validation instead of using offline validation (where the EMV chip on the card validates the PIN). ' example: true pin_required_pad_pres_but_no_pin_entered: type: boolean description: _Byte 3, bit 4._ Whether the merchant or cardholder chose to bypass PIN entry, and the PIN pad was operational. example: false pin_required_no_pad_or_bad_pad: type: boolean description: _Byte 3, bit 5._ Whether a PIN was required but there was no PIN pad, or the PIN pad wasn't working. example: true pin_try_limit_exceeded: type: boolean description: _Byte 3, bit 6._ Whether the PIN-try limit was exceeded. For example, the terminal read the PIN-try counter on the chip and it was zero. example: false cardholder_verification_not_successful: type: boolean description: _Byte 3, bit 8._ Whether the terminal indicates that cardholder verification was not successful. example: false required: - raw required: - is_emv version: type: string description: 'Auth API version of this webhook. Example: `"3.0"`' example: '3.0' iias_info: type: object description: _Visa only_. Present when the items or services being purchased include eligible medical expenses. Derived from Field 54 and Field 62. This object is present only when <> information is included with the authorization request. For more information, see IIAS fields in the _Auth API Field Detail_ guide. properties: iias_indicator: type: string description: '`M` indicates that the card is an <>, <>, or <> card. Field 62.4. Example: `"M"`' merchant_verification_value: type: string description: 'IIAS merchant verification value for the <>-certified merchant location. Field 62.20. Example: `"1234560000"`' qualified_healthcare_products_total: type: string description: 'Amount of `trans_amount` that qualifies as a healthcare product or service. Field 54, amount type 4S. Example: `"64.87"`' rx_total: type: string description: 'Amount that is prescription medication. Field 54, amount type 4U. Example: `"64.87"`' vision_total: type: string description: 'Amount that is vision-related. Field 54, amount type 4V. Example: `"0.00"`' clinic_total: type: string description: 'Amount that is a clinic visit. Field 54, amount type 4W. Example: `"0.00"`' dental_total: type: string description: 'Amount that is dental-related. Field 54, amount type 4X. Example: `"0.00"`' advanced_auth_api_fields: type: object description: 'Selected subfields parsed from the ISO 8583 message. These fields are sent only when ADVAF is set and only by arrangement with SoFi Tech Solutions. See Advanced Auth API Fields for more information. Example: `"advanced_auth_api_fields": {"61": {"subfield 1": , "subfield 2": }}`' properties: '[data element number]': type: object description: Number of the data element (DE). properties: subfield 1: type: string description: Raw contents of the subfield. subfield 2: type: string description: Raw contents of the subfield. subfield N: type: string description: Raw contents of the subfield. tar_info: type: object description: 'Tokenization authorization request (TAR) data is provided by the network during mobile wallet provisioning. The following are the subfields in a tokenization authorization request. Note the distinctions between Mastercard and Visa networks. For enhanced provisioning security based on some of these fields, see Enhanced provisioning security in _Setup for Mobile Wallets_. If you do not receive this data for provisioning approved BINs, contact SoFi Tech Solutions for assistance.' properties: correlation_id: type: string description: '_Mastercard only._ Identifier assigned that can be used by the issuer to associate related tokenization requests and notification messages. 14 alphanumeric characters. Example: `"D0002688797932"`' example: D0002688797932 pan_source: type: string description: 'For Mastercard, this field identifies the method by which the cardholder is attempting to tokenize a PAN. - `1` — Card on file - `2` — Card added manually - `3` — Card added via application For Visa, this tag, if present, identifies whether it’s push provisioning. - `01` — Key entered - `02` — On file - `03` — Mobile banking application - `04` — Token - `05` — Chip dip - `06` — Contactless If the value is `03`, then it is push provisioning.' enum: - '1' - '2' - '3' - '01' - '02' - '03' - '04' - '05' - '06' payment_app_instance_id: type: string description: '_Mastercard only._ Identifier associated with the payment application instance installed onto the customer''s device. 48 alphanumeric characters. Example: `"tSnaYXYaTSkz7DoGPz_wvVLhieie4lyhMPuMrvXx4kdAwkgV"`' example: tSnaYXYaTSkz7DoGPz_wvVLhieie4lyhMPuMrvXx4kdAwkgV device_ip: type: string description: 'For Mastercard, this field is the variable-length IP address. Each octet of the IP address is converted to hex and joined into one string, with the order maintained. 8 alphanumeric characters. Example: `"83BF5B74"` For Visa, this field contains the IP address of the device at the time of the provisioning request. 15 characters maximum. Example: `"255.255.255.255"`' acc_id_hash: type: string description: '_Mastercard only._ Contains the customer’s account ID associated with the wallet provider as a PBKDF2 hash. This account ID is typically the email address. The PBKDF2 function is performed using 10 iterations, a salt, and the lowercase account ID as the password. The salt is calculated by taking the lowercase UTF-8 bytes from the account ID and performing a SHA-256 hash operation. **Example**: Input (Password): `csharp@walletprovider.com` Salt: `"41404d1bca85ddb59ab21466e277ac1ac5f61470be120c82a21b1e45b5248123"` Count: `10` Output: `"7098014b646d44c6f3b454c5d54f7a32b3b46e2b0c8e2367f3e5307e3036dfe6"`' example: 7098014b646d44c6f3b454c5d54f7a32b3b46e2b0c8e2367f3e5307e3036dfe6 cardholder_name: type: string description: '_Mastercard only._ Contains the name of the cardholder. The format is represented in one of these two formats: - LASTNAME/FIRSTNAME with the names delimited by a slash `/`. Example: `"SMITH/JOE"` - FIRSTNAME LASTNAME. Example: `"JOE SMITH"` 27 characters maximum. If the cardholder’s name is longer than 27 positions, the data is truncated.' example: SMITH/JOE tokenization_recommendation: type: integer description: 'The tokenization decision suggested by the wallet provider. For Mastercard, possible values are: - `0` — Decline - `1` — Approve - `2` — Requires additional authentication For Visa, possible values are: - `0` — Unconditionally approved - `1` — Conditionally approved with further cardholder verification - `2` — Not approved' enum: - 0 - 1 - 2 tokenization_recommendation_standard_ver: type: string description: 'The version of the standards the wallet provider is using to determine the suggested tokenization recommendation. - For Mastercard, this value is 2 digits. Example: `"01"` - For Visa, this value is a decimal value. Example: `"0002.00"`' device_score: type: integer description: 'The score assigned by the wallet provider for the device. The score is returned as a value between `1` and `5`, with `5` being most trusted. Example: `5`' enum: - 1 - 2 - 3 - 4 - 5 account_score: type: integer description: '_Mastercard only._ Score assigned by the wallet provider for the <>. Value between`1` and `5`, with `5` being most trusted. Example: `5`' enum: - 1 - 2 - 3 - 4 - 5 active_tokens: type: string description: '_Mastercard only._ Number of existing, active tokens for the PAN, excluding card-on-file tokens. Space-filled when the requested token is digitized to a server. Example: `"08"`' example: 08 tokenization_recommendation_reason_code: type: string description: 'Indicates the specific reason the wallet provider is suggesting the tokenization recommendation. For Mastercard, the data of this field is a hex-encoded bitmap, whereby each bit corresponds to a specific reason code. If the wallet provider returns no reason, this field will contain spaces. See the possible values for Visa in the Tokenization Recommendation Reason Codes. Example: `"008011"`' tokenization_recommendation_reason_codes_parsed: type: string description: '_Mastercard only._ Indicates the specific reason the wallet provider is suggesting the tokenization recommendation. This field shows the interpretation of the hex-encoded bitmap in the `tokenization_recommendation_reason_code` field for Mastercard. See the possible values for this field in the Tokenization Recommendation Reason Codes. Example: `"08" `' location: type: string description: 'Latitude and longitude points where the cardholder''s device was located at the time the tokenization was attempted. - For Mastercard. The decimal latitude and longitude values, converted to hexadecimal. Example: `"2F197A2E1"` - For Visa, when available, the latitude and longitude points are provided with up to 4 digits of precision or rounded to a less-granular level. Example: `"+39.13/-77.55"`' last_four_digits: type: string description: '_Mastercard only._ Last four digits of the cardholder''s mobile phone number associated with the active wallet. Example: `"0885"`' example: 0885 token_type: type: string description: 'The type of requested token. - `C` — Mastercard cloud-based payments - `F` — Card on file - `S` — Embedded secure element - `H` — <> cloud token' enum: - C - F - S - H consumer_identifier: type: string description: '_Mastercard only._ Unique identifier for each cardholder, which must be verified by the financial institution before a cardholder can add their credentials to the payment-enabled device. Default: blank.' device_type: type: string description: '_Visa only._ Device type value. - `00` — Unknown - `01` — Mobile phone - `02` — Tablet - `03` — Watch - `04` — Mobile phone or tablet - `05` — Personal computer' enum: - 0 - 1 - 2 - 3 - 4 - 5 device_language: type: string description: '_Visa only._ Language used by the cardholder’s device. 3 characters maximum. Example: `"eng"` for English.' example: eng device_id: type: string description: '_Visa only._ The device ID. 48 characters maximum. Example: `"MTgwOTIxMTQzMjAwMTA0LUh0"`' example: MTgwOTIxMTQzMjAwMTA0LUh0 device_number: type: string description: '_Visa only._ Contains the device number, or the full or partial telephone number, when available. Provided by the Visa network. Example: `"15127717396"`' example: '15127717396' device_name: type: string description: '_Visa only._ The name of the device given by the cardholder. 16 characters maximum. Value is truncated when longer than maximum length. Example: `"Work Phone"`' example: Work Phone account_id: type: string description: '_Visa only._ Contains the wallet account ID. Example: `"eg2t6TyJQ2G8NIraaCypzg"`' example: eg2t6TyJQ2G8NIraaCypzg account_email_addr: type: string description: '_Visa only._ Contains the hashed full email address for the cardholder account that was sent by the wallet provider. Example: `"\xc1_\xf8\xc8_/\xd1%%\x06\xc4?_"`' example: Á_øÈ_/Ñ%%Ä?_ visa_token_score: type: string description: '_Visa only._ Contains the Visa Token Score associated with a token. Scores range from 01-99, with higher values indicating higher risk. `00` indicates a token was not scored. Example: `"01"`' example: '01' required: - correlation_id - pan_source - payment_app_instance_id - device_ip - acc_id_hash - cardholder_name - tokenization_recommendation - tokenization_recommendation_standard_ver - device_score - account_score - active_tokens - location - last_four_digits - token_type - consumer_identifier - device_id fleet_info: type: object description: Information that is provided for cards with fleet-card BINs, which are Mastercard only. See Fleet Cards for more information. properties: fleet_card_driver_number: type: integer description: 'Driver ID. 17 digits maximum. Example: `06123456`' fleet_card_vehicle_number: type: integer description: 'Vehicle ID. 17 digits maximum. Example: `03123`' fleet_prompt_data: type: integer description: 'Contains occurrences of the prompt code read from a card chip. There can be up to 5 prompt codes. Consult the documentation from Mastercard for the full list. Example: `002` (vehicle number)' merchant_override_indicator: type: integer description: 'Indicates if the merchant point-of-sale supports the fleet spend control override capability: `0` (does not support) or `1` (supports)' control_override_items: type: integer description: Provides merchants with information, on a transaction basis, to override purchase restrictions to allow products to be purchased that may not have otherwise been allowed. Only to be populated when DE106SE2 contains the value `1`, indicating that the merchant point-of-sale supports the fleet spend-control override capability. fuel_info: type: integer description: 'Contains item-level detail information of the motor fuel product(s) purchased at the POS (3 digit code). Can have up to 3 subfields. Consult the documentation from Mastercard for the full list. Example: `036` (racing fuel)' non_fuel_info: type: integer description: 'Contains item-level detail information of the non-fuel product(s) purchased at the POS. Can have up to 12 subfields. Consult the documentation from Mastercard for the full list. Example: `102` (car wash)' aifi_fields: type: object description: _Colombia only_. Information related to ATM issuer-fee inquiries. properties: issuer_fee_inquiry_indicator: type: string description: Contains `"01"` to indicate issuer-fee inquiry request. DE112SE035. pos_transaction_status: type: integer description: Contains `"8"` to indicate account-status inquiry (ASI) service. DE061SF7. issuer_fee_amt: type: string default: '0.0' description: 'Amount of the ATD (domestic ATM) fee. This amount is displayed to the cardholder as the issuer fee. DE112SE036. Example: `"15000.00"`' merchant_advice_code: type: - string - 'null' description: '_Mastercard only._ Contains the supported merchant advice code (MAC), if applicable: `03`, `40`, `41`, or `43`. The GMACD parameter must be set to `Y` to enable MAC decisioning.' example: '40' fraud_results: type: object description: _Mastercard only_. Contains the results from the Mastercard Fraud Rule Management Service. If you subscribe to this service, ask SoFi Tech Solutions to enable this object. Consult the documentation from Mastercard for DE048SE56 to interpret the values. properties: AQV: type: string description: 'GDV-based spend ranking. Example: `"400"`' example: '400' AQF: type: string description: 'Frequency-based spend ranking. Example: `"100"`' example: '100' AQS: type: string description: 'Segment qualifier. Example: `"002"`' example: '002' AIQ: type: string description: 'Digital transaction insights. Example: `"3QZ"`' example: 3QZ required: - AQV - AQF - AQS - AIQ fraud_scoring_data: type: object description: '_Mastercard only._ DE048SE75. Contains the results from Mastercard''s Expert Monitoring, Fraud Scoring Service, or Decision Intelligence (DI) service. If you subscribe to any of these services, ask SoFi Tech Solutions to enable this object. Consult the documentation from Mastercard for your service to interpret the values. ' properties: risk_assessment_score: type: integer description: 'Mastercard Decision Intelligence (DI) score ranging from `0-999`. Example: `"089"`' example: '89' risk_assessment_score_reason_code: type: string description: 'Fraud reason code. Indicates the key factors that influenced the value in `risk_assessment_score`. Example: `"64"`' example: '64' real_time_fraud_score: type: string description: 'The Fraud Rule Manager Service provides the rule-adjusted score of `000-999`, where `000` indicates the least likely fraudulent transaction and `999` indicates the most likely fraudulent transaction. Example: `"089"`' example: 089 real_time_fraud_score_reason_code_1: type: string description: 'An alphanumeric reason code that identifies the data used to derive the `real_time_fraud_score`. Example: `"64"`' example: '64' real_time_fraud_score_reason_code_2: type: string description: 'An alphanumeric reason code that identifies the data used to derive the `real_time_fraud_score`. Example: `"00"`' example: '00' digital_payment_data: type: object description: '_Mastercard only._ DE104SE4. Contains the results from Mastercard''s Token Authentication Framework (TAF) program. If you subscribe to Mastercard''s Expert Monitoring, Fraud Scoring Service, or Decision Intelligence (DI) service, ask SoFi Tech Solutions to enable this object to use for decisioning. Consult the documentation from Mastercard on DE104 Subelement 004 to interpret the values. ' properties: digital_service_provider: type: string description: 'Identifies the entity that authenticated the transaction. Consult the documentation from Mastercard for a complete list of values for DE104SE4SF1. Example: `"001005A0010"`' example: 001005A0010 digital_authentication_data: type: string description: 'Confirms that the transaction was fully authenticated, and identifies the authentication method used. Consult the documentation from Mastercard for a complete list of values for DE104SE5SF1. Example:`"0010054TRID00200500000"`' example: 0010054TRID00200500000 latest_incremental_id: type: integer description: 'The `auth_id` of the previous authorization in an incremental sequence when `incremental_auth: true`. This field contains the same information as `original_id` and is present only by request. Example: `13371854`' example: 13371854 original_incremental_id: type: integer description: 'The `auth_id` of the first authorization in an incremental sequence when `incremental_auth: true`. This field is present only by request. Example: `13369203`' example: 13369203 account_attack_intelligence_score: type: - string - 'null' description: '_Visa only_. A score for <> transactions to evaluate risk of enumeration attacks. Field 104, Dataset 5B, Tag 85. Valid values are `01-99` or null. Lower scores mean less risk. Example: `"24"`' example: 24 relay_resistance_protocol_data: type: object description: _Mastercard only_. DE048SE71. For tokenized (mobile wallet), contactless transactions, this is information captured at the terminal related to the possibility of relay attacks. For valid values, see Relay Resistance Protocol Data. properties: on_behalf_service: type: string description: 'The type of service performed on the transaction. Example: `"51"`' example: '51' result_1: type: string description: 'The first result from the on-behalf service. Example: `"A"`' example: A result_2: type: string description: 'The second result from the on-behalf service, if any. Example: `"K"`' example: K service_processing_type: type: - string - 'null' description: '_Visa only_. Service processing type for scheduled, deferred <>s. See Service Processing Types for valid values. Field 104 Dataset 57 Tag 80. Example: `"03"`' example: '03' visa_atm_managed_services: type: object description: _Visa only_. Managed-service information. Field 111 Dataset 02. properties: managed_service_indicator: type: string description: 'Whether this is a managed-service transaction. Tag 82. Example: `"Y"`' example: Y agreement_type: type: string description: 'The type of managed service that was provided for this transaction. Consult the documentation from Visa for valid values. Tag C1. Max 4 char. Example: `"1234"`' example: '1234' is_in_person_tap_transaction: type: boolean description: _Visa only_. Whether this is a direct in-person tap transaction. Applies only to <>s and <>s. Field 34. example: true vdcap_info: type: object description: _Visa only_. <> information from Field 34, Field 56, and Field 111. properties: authentication_program: type: string description: 'Indicates which authentication solution or data-sharing solution was used to process the transaction. See VDCAP Info for valid values. Field 34 Dataset 01 Tag C0. Example: `"01"`' example: '01' consumer_device_ip_address: type: string description: 'External IP address that is the device public IP address used by the 3DS requestor application when it connects to the 3DS requestor environment. Field 34 Dataset 01 Tag 92. Example: `"172.16.22.52"`' example: 172.16.22.52 applied_special_service: type: string description: 'Indicates whether the merchant has used the eligible authentication or data-sharing method and provided the required data elements. Visa sends `1` (<>) if all the conditions are met. Field 111 Dataset 56 Tag 89. Example: `"1"`' example: '1' other_phone_number: type: string description: 'A phone number belonging to the cardholder. Field 56 Dataset 02 Tag 83. Max 16 char. Example: `"8015552333"`' example: '8015552333' browser_ip_address: type: string description: '3DS browser IP address. Field 34 Dataset 01 Tag 89. Example `"10.0.45.66"`' example: 10.0.45.66 other_email_address: type: string description: 'An email address belonging to the cardholder. Field 56 Dataset 02 Tag 86. Max 99 char. Example: `"3dsuser@exampledomain.com"`' example: 3dsuser@exampledomain.com device_id: type: string description: 'Unique identifier associated with the cardholder device. Field 34 Dataset 06 Tag 86. Max 64 char. Example: `"device000"`' example: device000 credit_info: type: object description: Contains information related to credit accounts. properties: credit_card_balance: type: number description: 'The outstanding balance on a credit account. This value can be interpreted as being accurate as of the `opentobuy_ts`. Example: "-249.51"' example: '-249.51' opentobuy_ts: type: string description: 'Date and time when when the `credit_card_balance` was last captured. Format is YYYY-MM-DD hh:mm:ss.ssssss and timezone is always `MST`, which is Arizona time (GMT -0700). Example: `"2025-03-17 14:06:50.243654"`' example: '2025-03-17 14:06:50.243654' mastercard_transaction_id_data: type: object description: _Mastercard only_. Derived from DE105, Multi-Use Transaction Identification Data. Contains the <>, which is globally unique in a distributed environment and used as a single unique reference to perform matching and linking of all message activity properties: tlid: type: string description: 'DE105SE1. Transaction link identifier. A unique ID that Mastercard generates for each original transaction. Example: `"aabb112233445566"`' example: aabb112233445566 economically_related_tlid: type: string description: DE105SE2. The Mastercard-generated TLID from an economically related independent transaction that a customer retains and returns in subsequent economically related transactions. example: ff00ee11dd22cc33 lifecycle_tlid_validation_data: type: object description: Data relative to the TLID lifecycle. properties: action_indicator: type: string description: 'DE105SE3SF1. Indicates whether Mastercard modified the `tlid`, either because the customer did not provide a TLID in a lifecycle-linking scenario, or the TLID was unmatched. Possible values: - `1` — Mastercard populated `tlid` with the original message TLID. The customer did not submit a lifecycle message with a TLID, and so `customer_provided_tlid` will not be populated. - `2` — Mastercard populated `tlid` with the original lifecycle message TLID. The customer submitted the lifecycle message with a TLID value that did not match the original message. Mastercard moved the customer-provided TLID value to `customer_provided_tlid`. - `3` — Mastercard generated a new TLID value for `tlid`. Mastercard was unable to match this lifecycle message to any original message. If the customer submitted this transaction with a TLID value, Mastercard moved the customer-provided TLID value to `customer_provided_tlid`.' example: '2' customer_provided_tlid: type: string description: DE105SE3SF2. Contains the customer-provided TLID value from DE105SE1 (`tlid`) when Mastercard is unable to confirm the validity of that customer-provided TLID value. example: cc998877dd665544 required: - auth_type - transaction_type - id - timestamp - network - subnetwork - account - amounts - mcc - merchant - mti - transaction - validation_results - international - response_code - auth_id - partial_supported - entry_type - response_code_objects - ecommerce - eligible_for_balance_return - emv - version responses: '200': description: 'Use the fields in this schema to respond with your decision plus any instructions for SoFi Tech Solutions. ' content: application/json: schema: type: object properties: response_code: type: string description: 'Authorization response code, which specifies whether a transaction is approved or denied. See the Authorization Response Codes enumeration for possible values. Example: `"05"`' example: '05' avs_response: type: string description: 'Use this field to override `avs_result`, if you believe `avs_result` is wrong. See AVS Codes for valid values. Example: `"Y"`' override_limit: type: boolean description: 'Use this field to override authorization limits, if permitted. If this field is `true` then any limits that would be reached are overridden. Example: `true`' example: true partial_amount: type: number format: float minimum: 0 description: 'If `response_code` indicates a partial approval (`10` or `87`), this is the partial amount to approve. Example: `5.00`' example: 5 transfer_prn: type: string minLength: 12 maxLength: 12 description: 'If you want to perform a transfer to cover a lack of funds, this is the PRN of the account to supply the funds. Example: `"155200002717"`' example: '155200002717' transfer_amount: type: number format: float minimum: 0 description: 'The amount to transfer from the `transfer_prn` to the cardholder account. Example: `20.00`' example: 20 source_transfer_type: type: string description: 'The transaction type for the adjustment on the source account in `transfer_prn`. Use the value that SoFi Tech Solutions supplied. Case sensitive. Default: `pc`. Example: `"lm"`' minLength: 2 maxLength: 2 example: pc dest_transfer_type: type: string description: 'The transaction type for the adjustment to the cardholder account. Use the value that SoFi Tech Solutions supplied. Case sensitive. Default: `PC` Example: `"LM"`' minLength: 2 maxLength: 2 example: PC available_balance: type: number format: float description: 'If `eligible_for_balance_return: true` AND you hold the ledger for the card account, populate this field with the card account''s available balance to spend _before_ the transaction is performed. Otherwise, SoFi Tech Solutions sends the balance it has in the response message. The amount should be in the account currency. (The card networks will perform currency conversion as needed.) Example: `250.00`' example: 250 savings_balance: type: number format: float description: 'If `eligible_for_balance_return: true` AND you hold the ledger for the cardholder''s savings account, populate this field with the savings account balance in the currency of the account. Otherwise, SoFi Tech Solutions sends the balance it has in the response message. Example: `4000.00`' example: 4000 available_credit: type: number format: float description: 'If `eligible_for_balance_return: true` AND you hold the ledger for the cardholder''s credit account, populate this field with the credit limit remaining in the currency of the account. Otherwise, SoFi Tech Solutions sends the remaining limit it has in the response message. Example: `1500.00`' example: 1500 merchant_advice_code: type: string description: '*Mastercard only.* Use this field to override MAC decisioning, if permitted. Leave blank if you do not wish to override the SoFi Tech Solutions MAC decision. SoFi Tech Solutions reverts to the original decision if an invalid MAC is provided. The MACO product parameter must be set to `Y` to enable overrides.' example: '41' required: - response_code examples: Approve Transaction: summary: Approve transaction value: response_code: '00' Override avs_result: summary: Override AVS result value: response_code: '00' avs_response: Y Transfer: summary: Real-time transfer value: response_code: '00' transfer_prn: '155200002717' transfer_amount: 20 source_transfer_type: pc dest_transfer_type: PC available_balance: 250 Do Not Honor: summary: Override approval value: response_code: '05' Return Multiple Balances: summary: Return multiple balances value: response_code: '00' available_balance: 3654.22 savings_balance: 2450.89 available_credit: 354.34 components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT x-explorer-enabled: false x-samples-enabled: false x-readme: proxy-enabled: true