Auth API Webhook

Auth API Webhook 2.0

With this 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 <a href="doc:authorization-controller-api" target="_blank">Authorization Controller API</a> 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. For some optional fields, the key is omitted when there is no value — that is not the same as sending JSON null.

post/basepath/Authorization

Request

Base URL
https://example.client.domain.com
URL
https://example.client.domain.com/basepath/Authorization
Auth
HTTP bearer

Headers

X-Request-IDstring uuid required

A unique identifier for the HTTP request.

Request body

auth_type'Auth' | 'Advice' | 'Reversal' required

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.

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.

idstring required

Unique identifier for this authorization.

Example: "DHWJtI8zRjuDcgF8hru3oQ"

timestampstring required

Date and time when the webhook was sent by SoFi Tech Solutions.

Format is <timestamp><timezone>, where timestamp is YYYYMMDD:HHMMSS and timezone is always MST, which is Arizona time (GMT -0700).

Example: "20250315:121504MST"

Card network name. Possible values:

Visa
Allpoint
Discover
Mastercard
Star
Pulse

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

mccinteger required

Merchant category code. This value does not include leading zeros.

Example: 5992

mtistring required

Message-type indicator, as defined by ISO 8583. See <a href="doc:authorization-controller-api#message-types" target="_blank">Message types</a> in the Authorization Controller API guide.

Example: "0200"

internationalboolean required

Whether this is <a href="doc:international#what-counts-as-a-domestic-transaction" target="_blank">an international transaction</a>.

response_codestring required

Authorization response code, which specifies whether a transaction is approved or denied. See the <a href="page:authorization-response-codes#account-and-card-status-response-codes" target="_blank">Authorization Response Codes</a> enumeration for possible values.

Example: "05"

auth_idinteger required

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 <a href="doc:transaction-ids#authorization-identifiers" target="_blank">Authorization identifiers</a> in the Transaction IDs guide.

Example: 13371854

partial_supportedboolean required

Whether the merchant supports partial authorizations.

incremental_authboolean

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.

Method of entering the <glossary:PAN>, also known as <glossary:POS> entry mode. See <a href="ref:api-reference-de022-codes#entry_type-mapping" target="_blank">DE022 Codes</a> 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

pin_entry_capability'Capable' | 'Incapable' | 'Inoperative' | 'Other'

Condition of the PIN pad at the point of sale. See <a href="ref:api-reference-de022-codes#position-3" target="_blank">DE022 Codes</a> 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.

original_idinteger

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

risk_scorestring

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"

If this is a tokenized transaction, its type. Present only for tokenized transactions. Possible values:

Apple Inc
Google Inc.
Masterpass
Merchant
Microsoft
Samsung Corporation
Visa Checkout

rules_deniedstring[]

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"]

rules_warnedstring[]

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"]

response_code_liststring[] required

List of <a href="page:authorization-response-codes#account-and-card-status-response-codes" target="_blank">response codes</a> that SoFi Tech Solutions has computed. This list does not contain "00". May be empty.

Example: ["05", "51"].

baistring nullable

Business application identifier. Visa only. See the <a href="ref:api-reference-business-application-identifier" target="_blank">Business Application Identifier</a> enumeration for possible values.

Example: "FD"

risk_codestring

Mastercard only. Fraud reason code. Indicates the key factors that influenced the value in risk_score.

Example: "58"

eligible_for_balance_returnboolean required

Whether the cardholder's balance can be returned. This field is always true when transaction_type: Balance Inquiry. See <a href="doc:authorization-controller-api#balance-inquiry-responses" target="_blank">Balance-inquiry responses</a> in the Authorization Controller API guide for information on returning balances in the response to this message.

versionstring required

Auth API version of this webhook.

Example: "2.0"

merchant_advice_codestring nullable

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.

latest_incremental_idinteger

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

original_incremental_idinteger

The auth_id of the first authorization in an incremental sequence when incremental_auth: true. This field is present only by request.

Example: 13369203

account_attack_intelligence_scorestring nullable

Visa only. A score for <glossary:CNP> 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"

service_processing_typestring nullable

Visa only. Service processing type for scheduled, deferred <glossary:OCT>s. See <a href="ref:api-reference-service-processing-types" target="_blank">Service Processing Types</a> for valid values. Field 104 Dataset 57 Tag 80.

Example: "03"

is_in_person_tap_transactionboolean

Visa only. Whether this is a direct in-person tap transaction. Applies only to <glossary:OCT>s and <glossary:AFT>s. Field 34.

Example request

{
  "id": "DHWJtI8zRjuDcgF8hru3oQ",
  "timestamp": "20250315:121504MST",
  "account": {
    "xid": 5398373,
    "cad": 72450868,
    "prn": "999200002022",
    "product_id": 2577,
    "program_id": 566,
    "pan": "5198",
    "card_status": "N",
    "expiration_date": "2103",
    "track_expiration_date": "2103",
    "merchant_supplied_expiration_date": "2103"
  },
  "amounts": {
    "currency": "840",
    "trans_amount": "12.40",
    "partial_amount": "10.00",
    "cashback_amount": "5.00",
    "fee_amount": "1.50",
    "nearest_limit": "PCL Daily Limit",
    "local_currency": "124",
    "local_currency_amount": "21.00",
    "settle_currency": "978",
    "settle_currency_amount": "17.00",
    "billing_currency_amount": "12.40",
    "local_surcharge_amt": "0.50",
    "settle_surcharge_amt": "0.75",
    "settle_exchange_rate": "69985022",
    "exchange_rate": "65991234",
    "upcharge_amount": "75.00"
  },
  "mcc": 5992,
  "digital_commerce_data": {
    "entity_type_name": "202010030220",
    "domain_id": "01",
    "program_id": "01"
  },
  "merchant": {
    "acquirer_id": "406160",
    "terminal_id": "A1Z23B99",
    "merchant_id": "39AJKEO30634KVN3",
    "merchant_description": "123 WIDGETS MERCHANT     BEVERLY HILLSCA",
    "merchant_country": "840",
    "merchant_postal_code": "90210",
    "merchant_state": "NV",
    "terminal_network": "VPA"
  },
  "mti": "0200",
  "transaction": {
    "recurring": "N",
    "cardholder_present": "Y",
    "transaction_initiator_code": "M101",
    "is_advance_payment": true
  },
  "avs_data": {
    "zip": "84121",
    "address": "1235"
  },
  "international": true,
  "response_code": "05",
  "auth_id": 13371854,
  "partial_supported": true,
  "stip": {
    "detail": "9020"
  },
  "incremental_auth": true,
  "payment_info": {
    "sender_name": "John Doe",
    "fund_source": "Visa Prepaid"
  },
  "original_id": 13663253,
  "risk_score": "23",
  "response_code_list": [
    "05"
  ],
  "bai": "FD",
  "ecommerce": {
    "is_ecommerce": true,
    "aav_indicator": "kE",
    "merchant_asserts_data_protection": true,
    "merchant_authentication_assertions_validated": true,
    "cavv_result_code": "B"
  },
  "eligible_for_balance_return": true,
  "emv": {
    "is_emv": true,
    "brand": "visa",
    "terminal_verification_results": {
      "online_pin_entered": true,
      "pin_required_no_pad_or_bad_pad": true
    }
  },
  "version": "2.0",
  "tar_info": {
    "correlation_id": "D0002688797932",
    "payment_app_instance_id": "tSnaYXYaTSkz7DoGPz_wvVLhieie4lyhMPuMrvXx4kdAwkgV",
    "acc_id_hash": "7098014b646d44c6f3b454c5d54f7a32b3b46e2b0c8e2367f3e5307e3036dfe6",
    "cardholder_name": "SMITH/JOE",
    "active_tokens": "08",
    "last_four_digits": "0885",
    "device_language": "eng",
    "device_id": "MTgwOTIxMTQzMjAwMTA0LUh0",
    "device_number": "15127717396",
    "device_name": "Work Phone",
    "account_id": "eg2t6TyJQ2G8NIraaCypzg",
    "account_email_addr": "Á_øÈ_/Ñ%%\u0006Ä?_",
    "visa_token_score": "01"
  },
  "merchant_advice_code": "40",
  "fraud_results": {
    "AQV": "400",
    "AQF": "100",
    "AQS": "002",
    "AIQ": "3QZ"
  },
  "fraud_scoring_data": {
    "risk_assessment_score_reason_code": "64",
    "real_time_fraud_score": "089",
    "real_time_fraud_score_reason_code_1": "64",
    "real_time_fraud_score_reason_code_2": "00"
  },
  "digital_payment_data": {
    "digital_service_provider": "001005F0019002005A0001",
    "digital_service_provider_detail": {
      "001": "F0019",
      "002": "A0001"
    },
    "digital_authentication_data": "0010054TRID00200501020",
    "digital_authentication_data_detail": {
      "001": "4TRID",
      "002": "01020"
    }
  },
  "latest_incremental_id": 13371854,
  "original_incremental_id": 13369203,
  "relay_resistance_protocol_data": {
    "on_behalf_service": "51",
    "result_1": "A",
    "result_2": "K"
  },
  "service_processing_type": "03",
  "visa_atm_managed_services": {
    "managed_service_indicator": "Y",
    "agreement_type": "1234"
  },
  "is_in_person_tap_transaction": true,
  "vdcap_info": {
    "authentication_program": "01",
    "consumer_device_ip_address": "172.16.22.52",
    "applied_special_service": "1",
    "other_phone_number": "8015552333",
    "browser_ip_address": "10.0.45.66",
    "other_email_address": "3dsuser@exampledomain.com",
    "device_id": "device000",
    "account_owner_address_line_1": "123 MAIN ST",
    "account_owner_postal_code": "94105"
  },
  "credit_info": {
    "opentobuy_ts": "2025-03-17 14:06:50.243654"
  },
  "mastercard_transaction_id_data": {
    "tlid": "aabb112233445566",
    "economically_related_tlid": "ff00ee11dd22cc33",
    "lifecycle_tlid_validation_data": {
      "action_indicator": "2",
      "customer_provided_tlid": "cc998877dd665544"
    }
  }
}

Response

Use the fields in this schema to respond with your decision plus any instructions for SoFi Tech Solutions.

response_codestring required

Example: "05"

avs_responsestring

Use this field to override avs_result, if you believe avs_result is wrong. See <a href="ref:api-reference-avs-codes" target="_blank">AVS Codes</a> for valid values. Example: "Y"

override_limitboolean

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

partial_amountnumber float

If response_code indicates a partial approval (10 or 87), this is the partial amount to approve. Example: 5.00

transfer_prnstring

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"

transfer_amountnumber float

The amount to transfer from the transfer_prn to the cardholder account. Example: 20.00

source_transfer_typestring

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"

dest_transfer_typestring

The transaction type for the adjustment to the cardholder account. Use the value that SoFi Tech Solutions supplied. Case sensitive. Default: PC Example: "LM"

available_balancenumber float

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

savings_balancenumber float

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

available_creditnumber float

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

merchant_advice_codestring

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 response

{
  "response_code": "05",
  "override_limit": true,
  "partial_amount": 5,
  "transfer_prn": "155200002717",
  "transfer_amount": 20,
  "source_transfer_type": "pc",
  "dest_transfer_type": "PC",
  "available_balance": 250,
  "savings_balance": 4000,
  "available_credit": 1500,
  "merchant_advice_code": "41"
}

Changes

No recorded changes to this operation across all 1 revision of this API.