Visa Flex Credential API Reference
Visa Flex Credential
Authorization Decision API
The Authorization Decision API enables an authorization processor to request an authorization decision recommendation based on cardholder rules configured in consumer transaction controls. In addition, the API enables the authorization processor to update an authorization decision with the actual decision that was rendered.
NOTE: Future enhancements to this API may introduce new data elements being available in the payload. Client implementations should be designed to accommodate these enhancements to ensure existing behavior and functionality are not adversely impacted.
Retrieve the details of a specific decision record v1 - Latest
Retrieve the details of a specific decision record.
Request
path Parameters
| decisionID required |
string The ID of the document for the document to be returned |
query Parameters
| showControlsSnapShot | string This flag is required to view the controls snap shot at the time of processing the decision. |
Responses
200 OK
Response Schema: application/json
| processingTimeinMs required |
integer Processing time in milliseconds. Example: 15 |
| receivedTimestamp required |
string Time, in UTC, the request is received. Example: "2023-03-21 04:56:12.551" |
| resource required |
object |
| --- | --- |
| decisionID required |
string The decisionID assigned to the decision request. This value is generated by the API. |
| decisionRequest required |
object |
| --- | --- |
| cardholderBillAmount required |
number >= 0 Total amount to be billed to the cardholder inclusive of any fees assessed. Amount must be in the card issuers currency. Example: 100 |
| dateTimeLocal required |
string The date and time the transaction originated in the format: mmddhhmmss |
| decisionRequestTimeStamp required |
string Timestamp of when the decision was requested in UTC. Example: "2023-05-25 18:45:55" |
| decisionType required |
string [ 0 .. 15 ] characters The decision request type. Enum:"RECOMMENDED""COMPLETE""ADVICE""INFORM""PREAUTH" |
| merchantInfo required |
object |
| --- | --- |
| countryCode required |
string [ 0 .. 3 ] characters ([a-zA-Z]+) Three letter ISO ALPHA-3 country code for the merchant location. Example: "USA" |
| currencyCode required |
string 3 characters ISO 8583 three-digit currency classification code identifying the national currency used at the merchant location. Example: "840" |
| merchantCategoryCode required |
string 4 characters ([0-9]+) ISO 8583 four-digit merchant classification code identifying the merchant by their business line. Example: "5542" |
| addressLines | Array of strings Address of the merchant. Example: "1000 Main Street San Francisco, CA 94105" |
| cardAcceptorTerminalID | string non-empty Terminal ID of the card acceptor. Example: "45678" |
| city | string [ 0 .. 100 ] characters City where the merchant is located. Example: "San Francisco" |
| name | string [ 0 .. 50 ] characters Name of the merchant's business. Example: "Alex Miller Bakery" |
| postalCode | string [ 0 .. 10 ] characters Five to nine digit postal/zip code for the merchant. Example: "94105" |
| region | string [ 0 .. 3 ] characters Two or three letter state or region code. Example: "US" |
| transactionAmount | number >= 0 Total transaction amount in local merchant currency. Example: 200 |
| messageType required |
string 4 characters ([0-9]+) ISO message type Enum:"0100""0120""0200""0220""0400""0420" |
| processingCode required |
string 6 characters ([0-9]+) ISO processing code must be numeric, must be 6 positions |
| retrievalReferenceNumber required |
string non-empty Retrieval reference number assigned by the card acceptor. Example: "1101000000" |
| billerCurrencyCode | string 3 characters ISO 8583 three-digit currency classification code identifying the national currency used at the biller's location. Example: "840" |
| cardDetail | object |
| --- | --- |
| nameOnCard | string [ 0 .. 26 ] characters Cardholder name as encoded on the payment instrument. Example: "Alex Miller" |
| sequenceOnCard | string [ 0 .. 3 ] characters Card sequence number as encoded on the payment instrument. |
| decisionRequestTimeStampInMs | string Time, in UTC, the request is received. Example: "2023-05-25 18:45:55" |
| fxInfo | object |
| --- | --- |
| crossCurrencyIndicator | boolean Indicates if this transaction is cross currency or not. |
| visaExchangeRate | number Contains the rate used by VisaNet to convert the transaction amount (field 4) to the cardholder billing amount (field 6) including the optional issuer fee (OIF).When a Client participates in multi-currency feature, this field includes the VisaNet rate used to convert the transaction/cardholder billing amount to the currency of the control-type. Example: 0.05 |
| pointOfServiceInfo | object |
| --- | --- |
| presentationData required |
object |
| --- | --- |
| howPresented required |
string [ 0 .. 30 ] characters Identifies how the transaction entered the payment system Enum:"CUSTOMER_PRESENT""CUSTOMER_NOT_PRESENT""MAIL_PHONE_ORDER""RECURRING_TRANSACTION""INSTALLMENT_PAYMENT" |
| isCardPresent required |
boolean Identifies whether the card was present at the merchant location when the transaction entered the payment system |
| terminalClass required |
object |
| --- | --- |
| deviceLocation required |
string Defines the location of the card accepting device Enum:"ON_PREMISE""OFF_PREMISE""ELECTRONIC_COMMERCE" |
| howOperated required |
string [ 0 .. 25 ] characters Defines how the card accepting device was operated Enum:"CUSTOMER_OPERATED""CARD_ACCEPTOR_OPERATED""ADMINISTRATIVE" |
| isAttended required |
boolean Defines whether card accepting device is attended by a person |
| terminalEntryCapability required |
string [ 0 .. 30 ] characters identifies the form the primary account number was acquired Enum:"UNKNOWN""MANUAL""MAG_STRIPE_READ""BAR_CODE""OCR""ICC""KEY_ENTERED""FILE""MICR_READER""CONTACTLESS" |
| terminalType required |
string [ 0 .. 30 ] characters identifies the type of terminal at which the transaction was acquired Enum:"POS_TERMINAL""ATM""HOME_TERMINAL""MOBILE_DEVICE" |
| personalIdentificationNumberEntryMode | string [ 0 .. 30 ] characters identifies the way the PIN number was entered Enum:"UNKNOWN""PIN_ENTRY_CAPABLE""NO_PIN_ENTRY""PIN_PAD_INOPERATIVE" |
| primaryAccountNumberEntryMode | string [ 0 .. 30 ] characters identifies the way primary account number was entered Enum:"UNKNOWN""MANUAL""MAG_STRIPE_READ""BAR_CODE""OCR""ICC""KEY_ENTERED""FILE""MICR_READER""CONTACTLESS" |
| securityCondition | string [ 0 .. 60 ] characters identifies information about how the payment transaction was authenticated Enum:"NO_SECURITY_CONCERN""SUSPECTED_FRAUD""IDENTIFICATION_VERIFIED""SECURE_ELECTRONIC_COMMERCE""NOT_AUTHORIZED_AT_3D_SECURE_MERCHANT""NOT_AUTHENTICATED_SECURITY_TRANSACTION""NON_SECURE_TRANSACTION""NOT_AUTHENTICATED_SECURITY_TRANSACTION_SET_MERCHANT""CVV_VALIDATED_AND_VALID""CVV_VALIDATED_AND_INVALID" |
| transactionID | string Unique transaction ID assigned by processing gateway. If non-Visa processed transaction, transactionID is assigned by the issuer system. Example: "2101000000" |
| transactionTypes | Array of strings non-empty A list of transaction types that this decision qualifies for. If this value is present then messageType, processingCode, and pointOfServiceInfo will be ignored. Items Enum:"TCT_OCT""TCT_PURCHASE_RETURN""TCT_AUTO_PAY""TCT_E_COMMERCE""TCT_CONTACTLESS""TCT_BRICK_AND_MORTAR" |
| wasProcessorDeclined | boolean Provided along with decision type INFORM to indicate if the transaction was declined or approved . |
| decisionResponse required |
object |
| --- | --- |
| decisionResponseTimeStamp required |
string This value will be set automatically when the decision response is sent. Value is in UTC time Example: "2022-05-25 18:45:55" |
| shouldAlert required |
boolean Indicates whether an alert should be generated |
| shouldDecline required |
boolean Indicates the decline decision/recommendation depending on decision type |
| alertsRuleDetail | Array of objects unique List of rules that triggered alerts, only present when alerts are triggerd for a decision |
| Array |
| ruleCategory required |
string Rule category for the control that triggered the alert/decline. Enum:"PCT_GLOBAL""PCT_TRANSACTION""PCT_MERCHANT" Example: "PCT_GLOBAL" |
| ruleType required |
string Rule type for the control that triggered the alert/decline. Enum:"TCT_ATM_WITHDRAW""TCT_AUTO_PAY""TCT_BRICK_AND_MORTAR""TCT_CROSS_BORDER""TCT_E_COMMERCE""TCT_CONTACTLESS""TCT_PURCHASE_RETURN""TCT_OCT""MCT_ADULT_ENTERTAINMENT""MCT_AIRFARE""MCT_ALCOHOL""MCT_APPAREL_AND_ACCESSORIES""MCT_AUTOMOTIVE""MCT_CAR_RENTAL""MCT_ELECTRONICS""MCT_SPORT_AND_RECREATION""MCT_GAMBLING""MCT_GAS_AND_PETROLEUM""MCT_GROCERY""MCT_HOTEL_AND_LODGING""MCT_HOUSEHOLD""MCT_PERSONAL_CARE""MCT_SMOKE_AND_TOBACCO""MCT_DINING""NONE" Example: "TCT_ATM_WITHDRAW" |
| triggeringAppID required |
string App ID for the control that triggered the alert. Example: "vd-b971963f-12d9-4a28-a8dc-80bf9c31" |
| alertReason | string Reason for the alert. Only present in alertDetails. Enum:"DECLINE_ALL""DECLINE_TRANS_LIMIT""DECLINE_BREACHED_AMT""ALERT_BREACHED_AMT""DECLINE_BY_ISSUER""DECLINE_BY_SPEND_LIMIT""ALERT_BREACHED_SPEND""FX_ALERTS""ALERT_BREACHED_AMT_REVERSAL" Example: "DECLINE_TRANS_LIMIT" |
| controlTargetType | string Defines the control level that triggered the alert/decline. Example: "CARD_LEVEL" |
| thresholdAmount | number Threshold amount for the control that triggered the alert/decline. Only present if thresholdAmount breach caused the trigger. Example: 1000 |
| userIdentifier | string Uniquely identifies the cardholder to receive the alert. Should be a GUID, must be unique per enrolling application. Must not contain any PII data. Mandatory for all VTC notifications. Maximum of 50 characters. Example: "b2d1b9cc-fc3f-4a37-b431-ebf04f20a3e9" |
| userInformation | object |
| --- | --- |
| name required |
string [ 0 .. 50 ] characters ^[a-zA-Z0-9 ._-]* Name of the user who configured the control. Required if userInformation is present. Example: "Alex Miller" |
| applicationDefinedAttributes | Array of strings Application attributes defined by the issuer. Example: "APP" |
| bankingIdentifier | string Identifier for the issuer to map the username. Example: "BI" |
| declineControlTargetType | string Defines the control level that triggered the alert/decline. Example: "CARD_LEVEL" |
| declineRuleCategory | string indicates the decline Rule Category that triggered the decline decision, only present when shouldDecline is true |
| declineRuleDetail | object |
| --- | --- |
| ruleCategory required |
string Rule category for the control that triggered the alert/decline. Enum:"PCT_GLOBAL""PCT_TRANSACTION""PCT_MERCHANT" Example: "PCT_GLOBAL" |
| ruleType required |
string Rule type for the control that triggered the alert/decline. Enum:"TCT_ATM_WITHDRAW""TCT_AUTO_PAY""TCT_BRICK_AND_MORTAR""TCT_CROSS_BORDER""TCT_E_COMMERCE""TCT_CONTACTLESS""TCT_PURCHASE_RETURN""TCT_OCT""MCT_ADULT_ENTERTAINMENT""MCT_AIRFARE""MCT_ALCOHOL""MCT_APPAREL_AND_ACCESSORIES""MCT_AUTOMOTIVE""MCT_CAR_RENTAL""MCT_ELECTRONICS""MCT_SPORT_AND_RECREATION""MCT_GAMBLING""MCT_GAS_AND_PETROLEUM""MCT_GROCERY""MCT_HOTEL_AND_LODGING""MCT_HOUSEHOLD""MCT_PERSONAL_CARE""MCT_SMOKE_AND_TOBACCO""MCT_DINING""NONE" Example: "TCT_ATM_WITHDRAW" |
| triggeringAppID required |
string App ID for the control that triggered the alert. Example: "vd-b971963f-12d9-4a28-a8dc-80bf9c31" |
| alertReason | string Reason for the alert. Only present in alertDetails. Enum:"DECLINE_ALL""DECLINE_TRANS_LIMIT""DECLINE_BREACHED_AMT""ALERT_BREACHED_AMT""DECLINE_BY_ISSUER""DECLINE_BY_SPEND_LIMIT""ALERT_BREACHED_SPEND""FX_ALERTS""ALERT_BREACHED_AMT_REVERSAL" Example: "DECLINE_TRANS_LIMIT" |
| controlTargetType | string Defines the control level that triggered the alert/decline. Example: "CARD_LEVEL" |
| thresholdAmount | number Threshold amount for the control that triggered the alert/decline. Only present if thresholdAmount breach caused the trigger. Example: 1000 |
| userIdentifier | string Uniquely identifies the cardholder to receive the alert. Should be a GUID, must be unique per enrolling application. Must not contain any PII data. Mandatory for all VTC notifications. Maximum of 50 characters. Example: "b2d1b9cc-fc3f-4a37-b431-ebf04f20a3e9" |
| userInformation | object |
| --- | --- |
| name required |
string [ 0 .. 50 ] characters ^[a-zA-Z0-9 ._-]* Name of the user who configured the control. Required if userInformation is present. Example: "Alex Miller" |
| applicationDefinedAttributes | Array of strings Application attributes defined by the issuer. Example: "APP" |
| bankingIdentifier | string Identifier for the issuer to map the username. Example: "BI" |
| declineRuleType | string indicates the decline Rule type that triggered the decline decision, only present when shouldDecline is true |
| declineThresholdAmount | number indicates the decline threshold amount that was used to trigger the decline decision, only present when shouldDecline is true and a decline threshold has been defined. |
| responseMessage | string This field provides more information on the disposition of the response Value:"CARD_NOT_ENROLLED" |
| decisionUpdate required |
object |
| --- | --- |
| decisionType required |
string [ 0 .. 15 ] characters The decision request type Value:"COMPLETE" |
| lastUpdateTimeStamp required |
string This field will be set automatically when the decision update is received. Value is in UTC time. |
| transactionApproved required |
string The decision for the completed transaction Enum:"APPROVED""DECLINED" |
| isDeclineResultOfTransactionControl | boolean Indicates whether the decline decision is the result of the transaction control recommendation. If not present true will be assumed |
| primaryAccountNumber required |
string [ 16 .. 23 ] characters Masked primary account number. Only the last 4 digits provided. Example: "xxxx-xxxx-xxxx-9010" |
| paymentToken | string [ 16 .. 23 ] characters Masked payment token. Only the last 4 digits provided. Example: "xxxx-xxxx-xxxx-9010" |
| transactionControlsnapshot | Array of objects |
| Array |
| createdOnDate | string Timestamp when control was added, in UTC Example: "2023-03-21 04:56:12.561" |
| documentID | string System-generated ID for the control document bound to the account identifier (primaryAccountNumber/paymentToken). Example: "ctc-vd-857a8766-160b-498d-820f-bf4339949c1b" |
| globalControls | Array of objects Used to set rules that apply to all transactions performed with this account. |
| Array |
| isControlEnabled required |
boolean Indicates if this control type will be applied during transaction processing. |
| alertThreshold | number Maximum value of an approved purchase for this control type before triggering an alert when purchase meets/exceeds limit. During authorization processing, the cardholderBillAmount is used to identify if an alert should be sent. Example: 1000 |
| declineAllNonTokenizeTransactions | boolean When set to "true," transactions performed with primaryAccountNumber will be declined. Only token-based transactions will continue to process as normal. Used when the physical card is lost or misplaced but the cardholder wants to continue transacting via their mobile phone. |
| declineThreshold | number Maximum value of a purchase for this control type before triggering a decline when purchase meets/exceeds limit. During authorization processing, the cardholderBillAmount is used to identify if a decline should be triggered. Example: 1000 |
| filterByCountry | object |
| --- | --- |
| controlDisabledCountryList | Array of strings unique List of countries where this control will not be applied. Uppercase ISO 3166 3-letter country code. Example: "[USA]" |
| controlEnabledCountryList | Array of strings unique List of countries where this control will be applied. Uppercase ISO 3166 3-letter country code. Example: "[USA]" |
| shouldAlertOnDecline | boolean Indicates if VTC will trigger a decline notification for all transactions matching the associated control type. If false, no alerts will be sent for declined transactions related to this control type. |
| shouldDeclineAll | boolean Indicates if VTC will trigger a decline for all transactions related to this control type. Default value will be false. If false, other control settings (e.g. declineThreshold) will be checked. |
| spendLimit | object |
| --- | --- |
| currentPeriodSpend required |
number Total amount of all approved transactions performed within the time period for this control type. Reset once a new time period begins by the amount of the first transaction. Example: 200 |
| declineThreshold required |
number Maximum total value of approved purchases within the time period before triggering a decline. Example: 1000 |
| type required |
string Time period that the control spans. LMT_MONTH: until the end of that month. LMT_WEEK: 7-day period. LMT_DAY: 24 hour period. LMT_DATE_RANGE: date range specified in startDateTime and endDateTime. LMT_RECURRING: recurring period, number of days specified in recurringCycleTime. Enum:"LMT_MONTH""LMT_WEEK""LMT_DAY""LMT_DATE_RANGE""LMT_RECURRING" Example: "LMT_WEEK" |
| alertThreshold | number Maximum total value of approved purchases within the time period before triggering an alert. Purchases that meet or exceed the limit set to this control type will not trigger another spendLimit alert until everything is reset when the next time period begins. Example: 1000 |
| endDateTime | string End time in UTC of a timeRange that bounds a control. Only transactions attempted during the specified timeRange will trigger this control. The format of the string is in 24hr time using HH:MM format. Example: "2023-03-21 04:56:56" |
| recurringCycleTime | integer Number of days after which the currentPeriodSpend is reset and a new cycle begins. Required only when type = LMT_RECURRING; in all other cases, the field is optional and even if present, it will be ignored. Example: 366 |
| startDateTime | string Starting date and time of a date and time range bounding a control, in the time zone set by the timeZoneID. Only transactions attempted during the specified date and time range will trigger this control. Cannot be in the past. Format is "CCYY-MM-DD HH:MM". The hour and minute portion is optional: if not provided, these values will be set to "00:00". This field is required only when type = LMT_DATE_RANGE. If it set when the type = LMT_RECURRING, the control will become active at that time, as if the user set the recurring functionality at that point in time. In all other cases the field is optional and even if present, it will be ignored. Example: "2023-03-21 04:56" |
| timeZoneID | string Time zone to be applied to related object in Area/Location format. For example: 'America/Denver' is in United States MST. If not provided, assumed to be UTC. timeZoneID can be applied within timeRange and spendLimit fields to affect endDateTime, startDateTime, endTime, and startTime fields. Example: "UTC" |
| timeRange | object |
| --- | --- |
| endTime required |
string End time in UTC of a timeRange that bounds a control. Only transactions attempted during the specified timeRange will trigger this control. The format of the string is in 24hr time using HH:MM format. Example: "04:56" |
| startTime required |
string Start time in UTC of a timeRange that bounds a control. Only transactions attempted during the specified timeRange will trigger this control. Formatted in 24hr time using HH:MM format. Example: "04:56" |
| timeZoneID required |
string Time zone to be applied to related object in Area/Location format. For example: 'America/Denver' is in United States MST. If not provided, assumed to be UTC. timeZoneID can be applied within timeRange and spendLimit fields to affect endDateTime, startDateTime, endTime, and startTime fields. Example: "UTC" |
| transactionLimit | object |
| --- | --- |
| maxTransactionCount required |
integer Number of transactions permitted. After the transaction count is reached, then subsequent transactions are declined. Counts apply to specific processing codes, on Visa processed transactions, and is limited to the Global control type. Example: 10 |
| currentTransactionCount | integer Total number of transactions approved since the start of this limit. Counts will apply where processing code is present, on Visa processed transactions. currentTransactionCount is limited for use only with the Global control type. Example: 10 |