Webhooks
When a Collaborative Authorization communication is received from the card issuer pertaining to a card-originated transaction, it will be parsed by connectFi and the system will then make a single POST request to your preset webhook URL with a body similar to the examples provided below.
It is important to note that some fields may alter the interpretation of other fields. For example, if you receive an "advice" webhook with a "type" of "debit", but the "advice.isReversal" field is true, then the flow of funds for the indicated transaction would actually be in reverse. If a "debit" occurs when a consumer makes a purchase, the funds will be pulled from (or deducted from) the card available balance. However, if this transaction is then reversed, the funds will be pushed back onto the card available balance.
Webhook Body for "request" actionType
{
"transaction": {
"transmissionDate": "2024-04-23T18:29:64Z",
"authTransactionId": "000000000088", //All webhooks related to this transaction will have the same authTransactionId
"actionType": "request",
"type": "debit",
"typeDescription": "Purchase",
"transactionAmount": {
"amount": 100,
"currency": "USD"
},
"ledgerBalance": {
"amount": 98597.66,
"currency": "USD",
"sign": "C"
},
"availableBalance": {
"amount": 98447.66,
"currency": "USD",
"sign": "C"
},
"message": {
"messageType": "0100",
"primaryAccountNumber": "110195062152752",
"processingCode": {
"transactionType": "00",
"accountTypeFrom": "00",
"accountTypeTo": "00"
},
"transactionAmount": {
"amount": 100,
"currency": "USD"
},
"cardholderBillingAmount": {
"amount": 100
},
"traceNumber": "002261",
"transmissionDate": "2024-04-23T18:29:64Z",
"localDate": "2024-04-23T14:29:64",
"dateSettlement": "2024-04-23",
"transactionFee": {
"amount": 0,
"sign": "D"
},
"acquirerId": "12345678900",
"retrievalReferenceNumber": "000000000088",
"authIdentificationResponse": "123456",
"merchant": {
"mcc": "5999",
"code": "CARD ACCEPTOR ",
"terminalId": "TERMID01",
"address": "ACQUIRER NAME",
"city": "New York",
"country": "USA"
},
"additionalAmounts": [
{
"accountType": "00",
"amountType": "01",
"currency": "USD",
"sign": "C",
"amount": 98597.66
},
{
"accountType": "00",
"amountType": "02",
"currency": "USD",
"sign": "C",
"amount": 98447.66
}
],
"pos": {
"dateAndPANMode": "07",
"pinCapability": "2",
"conditionCode": "00"
},
"posData": {
"attendance": "0",
"operator": "0",
"terminalLocation": "0",
"cardholderPresence": "0",
"cardPresence": "0",
"cardRetention": "0",
"transactionStatus": "0",
"transactionSecurity": "0",
"terminalType": "04",
"terminalInput": "02",
"chipCondition": "0",
"specialCondition": "0",
"chipTransaction": "0",
"cardholderIDMethod": "0"
},
"networkData": {
"acquirerId": "0002",
"transactionIdentifier": "468062054217760",
"acquirerReferenceNumber": "0",
"networkType": "VISA"
},
"ledgerBalance": {
"amount": 98597.66,
"currency": "USD",
"sign": "C"
},
"availableBalance": {
"amount": 98447.66,
"currency": "USD",
"sign": "C"
},
"additionalData": {
"1": "I",
"2": "468062054217760",
"4": "H",
"5": "07",
"7": "000000",
"9": "000000",
"10": "00",
"11": "00",
"13": "000000000000",
"17": "0000000000",
"21": "0002",
"22": "0000",
"23": "0000",
"24": "00000000",
"27": "00",
"30": "0",
"33": "000000000000000",
"39": "0",
"40": "0000",
"42": "0000000000",
"44": "0000",
"47": "0",
"50": "00000000000",
"54": "00"
}
}
},
"cFiCardId": "icrd_7kLj9RSVzlwOtNb8vd6lPW"
}
Webhook Body for "advice" actionType
{
"transaction": {
"transmissionDate": "2024-04-23T18:29:00Z",
"authTransactionId": "000000000088", //All webhooks related to this transaction will have the same authTransactionId
"actionType": "advice",
"type": "debit",
"typeDescription": "Purchase",
"transactionAmount": {
"amount": 100,
"currency": "USD"
},
"advice": {
"isSuccess": true,
"isReversal": false,
"statusCode": "00"
},
"ledgerBalance": {
"amount": 98597.66,
"currency": "USD",
"sign": "C"
},
"availableBalance": {
"amount": 98347.66,
"currency": "USD",
"sign": "C"
},
"message": {
"messageType": "0220",
"primaryAccountNumber": "110195062152752",
"processingCode": {
"transactionType": "00",
"accountTypeFrom": "00",
"accountTypeTo": "00"
},
"transactionAmount": {
"amount": 100,
"currency": "USD"
},
"cardholderBillingAmount": {
"amount": 100,
"currency": "USD"
},
"traceNumber": "002262",
"transmissionDate": "2024-04-23T18:29:00Z",
"localDate": "2024-04-23T14:29:00",
"dateSettlement": "2024-04-23",
"transactionFee": {
"amount": 0,
"sign": "D"
},
"retrievalReferenceNumber": "000000000088",
"responseCode": "00",
"merchant": {
"mcc": "5999",
"code": "CARD ACCEPTOR ",
"terminalId": "12345678",
"address": "ACQUIRER NAME",
"city": "New York",
"state": "CA",
"country": "USA"
},
"additionalAmounts": [
{
"accountType": "00",
"amountType": "01",
"currency": "USD",
"sign": "C",
"amount": 98597.66
},
{
"accountType": "00",
"amountType": "02",
"currency": "USD",
"sign": "C",
"amount": 98347.66
}
],
"pos": {
"dateAndPANMode": "90",
"pinCapability": "2",
"conditionCode": "00",
"pinCaptureCode": "00"
},
"posData": {
"attendance": "0",
"operator": "0",
"terminalLocation": "0",
"cardholderPresence": "0",
"cardPresence": "0",
"cardRetention": "0",
"transactionStatus": "0",
"transactionSecurity": "0",
"terminalType": "04",
"terminalInput": "02",
"chipCondition": "0",
"specialCondition": "0",
"chipTransaction": "0",
"cardholderIDMethod": "0"
},
"networkData": {
"acquirerId": "0002",
"transactionIdentifier": "314100101842263",
"acquirerReferenceNumber": "0",
"networkType": "VISA"
},
"ledgerBalance": {
"amount": 98597.66,
"currency": "USD",
"sign": "C"
},
"availableBalance": {
"amount": 98347.66,
"currency": "USD",
"sign": "C"
},
"additionalData": {
"1": "A",
"2": "314100101842263",
"4": "H",
"5": "07",
"7": "000000",
"9": "000000",
"10": "02",
"11": "99",
"13": "000000000000",
"17": "0000000000",
"21": "0002",
"22": "2105",
"23": "0000",
"24": "00000000",
"27": "00",
"30": "0",
"33": "000000000000000",
"39": "0",
"40": "0000",
"42": "0000000000",
"44": "0000",
"47": "0",
"50": "00000000000",
"54": "00"
}
}
},
"cFiCardId": "icrd_7kLj9RSVzlwOtNb8vd6lPW"
}
Webhook Schema
Schema for Webhook Body Sent from connectFi
The following schema describes the potential fields that you may receive in the Collaborative Authorization Webhook.
-
For the statusCode field, see also "responseCode".
-
For a description of the 'transactionType' field values, see the Transaction Type Codes table in the Code Tables section of this documentation.
collaborativeAuthorizationWebhookSchema
Expected Response
Expected Response to actionType: "advice" Webhook
Then the webhook actionType is "advice", the connectFi server will expect the following response from your webhook server.
Expected Response to actionType: "request" Webhook
When the webhook actionType is "request", the connectFi server will expect to receive a response back from your webhook server with the following body.
The table below specifies allowed "responseCode" values.
| responseCode value | Description |
|---|---|
| "00" | Approved |
| "05" | Do not Honor |
| "34" | Suspect Fraud |
| "61" | Exceeds Withdrawal Amount Limit |
| "65" | Exceeds Withdrawal Frequency Limit |
Code Tables
Chip Condition Codes
| Chip Condition Code | Description |
|---|---|
| "0" | "Not applicable to fallback transactions." |
| "1" | "This value applies to fallback transactions. Transaction was initiated from a magnetic stripe with a service code beginning with 2 or 6 and the last read at VSDC terminal was a successful chip read or was not a chip transaction." |
| "2" | "This value applies to fallback transactions. Transaction was initiated at a chip-capable terminal from a magnetic stripe that contains service code 2 or 6, and the previous transaction initiated by that terminal was an unsuccessful chip read." |
Chip Transaction Indicators
| Chip Transaction Indicator | Description |
|---|---|
| "0" | "Not applicable; subsequent sub-fields are present When an Early Data option acquirer, or a Full Data option acquirer, submits Early Data, field 60.6 must contain zero (0) or be excluded from the message." |
| "1" | "This value is sent by acquirers using either the standard third bitmap or field 55 to submit chip data." |
| "2" | "This value is sent by acquirers using the expanded third bitmap for their chip data. The value 2 applies only to acquirers; V.I.P. changes it to 1 before the request is forwarded to the issuer." |
| "3" | "V.I.P. (not the acquirer) inserts this code and downgrades the transaction by dropping chip data section." |
| "4" | "V.I.P inserts this code based on the presence of a Visa issued token." |
Mail/Phone/Electronic Commerce and Payment Indicators
| Mail/Phone/Electronic Commerce and Payment Indicator | Description |
|---|---|
| "0" | "Not Applicable" |
| "1" | "Unknown/Unspecified" |
| "2" | "Not an e-commerce transaction" |
| "3" | "VSingle transaction of a mail/phone order" |
| "4" | "Recurring transaction" |
| "5" | "Installment payment" |
| "6" | "Secure electronic commerce transaction" |
| "7" | "Non-authenticated security transaction at a 3-D Secure-capable merchant, and merchant attempted to authenticate the cardholder using 3-D Secure" |
| "8" | "Non-authenticated Security Transaction" |
| "9" | "Non-secure transaction" |
| "A" | "In-App Authentication" |
| "B" | "Electronic commerce transaction with digital signature" |
| "C" | "Secure electronic transaction with cardholder certificate" |
| "D" | "Secure electronic transaction without cardholder certificate" |
| "E" | "Channel-encrypted electronic commerce transaction" |
| "F" | "UnionPay safe entry mode authentication conducted, and cardholder security information is input successfully" |
| "G" | "Certification of Issuer SAA direct authentication authorization conducted, and the SAA authentication authorization is successful" |
| "H" | "Authentication of Issuer SA direct status verification conducted, and the cardholder status verification is successful" |
| "I" | "Tried to conduct the issuer direct status verification" |
| "J" | "Failed CUPSecure safe authentication, but adopt the security technology of channel" |
| "K" | "Failed CUPSecure safe authentication, and does not adopt the security technology of encryption." |
| "L" | "Issuer Authentication Mode in card-no-present self-service transactions" |
| "M" | "Issuer Non-Authentication Mode in card-no-present self-service transaction" |
| "N" | "Static UCAF Value (Switch assigned static AAV)" |
| "O" | "Issuer Risk based Decision" |
| "P" | "Aquirer Risk based Decision" |
| "Q-Z" | "Reserved" |
MTI Codes
| Message Type Identifier/MTI Code | Description |
|---|---|
| "0100" | "Authorization Request" or "Token Provisioning - Send OTP Request" |
| "0110" | "Authorization Response" or "Token Provisioning - Send OTP Response" |
| "0120" | "Token OTP Notification" or "Advice Authorization Request" |
| "0130" | "Token OTP Notification Response" or "Authorization Advice Response" |
| "0200" | "Financial Transaction Request" |
| "0210" | "Financial Transaction Response" |
| "0220" | "Financial Transaction Advice" |
| "0230" | "Financial Transaction Response" |
| "0302" | "File Update Request" |
| "0312" | "File Update Request Response" |
| "0420" | "Reversal Advice" |
| "0430" | "Reversal Advice Response" |
| "0600" | "Administrative Request" |
| "0620" | "Administrative Advice" |
| "0630" | "Administrative Advice Response" |
| "0800" | "Network Management Request (Mandatory for TCP/IP Communication)" |
| "0810" | "Network Management Response (Mandatory for TCP/IP Communication)" |
Response Codes/Status Codes
| Response/Status Code | Description |
|---|---|
| "00" | "Approved" |
| "01" | "Refer to Card Issuer" |
| "02" | "Refer to Card Issuer, Special Condition" |
| "03" | "Invalid Merchant" |
| "04" | "Lost/Stolen Card" |
| "05" | "Do not Honor" |
| "06" | "Error" |
| "07" | "Pick-up Card, Special Condition" |
| "08" | "Honor with Identification" |
| "10" | "Approved - Partial Amount" |
| "12" | "Invalid Transaction" |
| "13" | "Invalid Amount" |
| "14" | "Invalid Card Number" |
| "15" | "Invalid Issuer" |
| "17" | "Customer Cancellation, Reversal" |
| "27" | "Issuer File Update Field Edit Error" |
| "30" | "Format Error" |
| "31" | "Bank Not Supported by Switch (Future Use)" |
| "32" | "Partial Reversal" |
| "33" | "Expired Card, Pick-up" |
| "34" | "Suspect Fraud" |
| "39" | "No Credit Account (Future Use)" |
| "40" | "Requested Function Not Supported" |
| "41" | "Lost Card Not Captured" |
| "42" | "No universal account" |
| "43" | "Stolen Card, Pick-up" |
| "51" | "Insufficient Funds" |
| "52" | "No Checking Account (Future Use)" |
| "53" | "No Savings Account (Future Use)" |
| "54" | "Expired Card" |
| "55" | "Invalid PIN" |
| "56" | "No Card Account" |
| "57" | "Transaction not Permitted to Cardholder" |
| "58" | "Transaction not Permitted to Acquirer/Terminal" |
| "59" | "Suspected Fraud" |
| "61" | "Exceeds Withdrawal Amount Limit" |
| "62" | "Restricted Card" |
| "63" | "Decline Error in Decryption of PIN Block / Security Violation" |
| "64" | "Original Amount Incorrect, Reversal" |
| "65" | "Exceeds Withdrawal Frequency Limit" |
| "68" | "Response Received Late" |
| "70" | "Invalid Transaction; Contact Card Issuer" |
| "71" | "PIN Change Decline" |
| "75" | "Allowed Number of PIN Tries Exceeded" |
| "76" | "Invalid/Nonexistent “To” Account Specified (Future Use)" |
| "77" | "Invalid/Nonexistent “From” Account Specified (Future Use)" |
| "78" | "Invalid/Nonexistent Account Specified (General) (Future Use)" |
| "79" | "Key Exchange Validation Failed" |
| "80" | "System not Available (Future Use)" |
| "81" | "Invalid Transaction (PIN Block Format Error)" |
| "82" | "Time Out Issuer" |
| "84" | "Invalid Authorization Life Cycle" |
| "85" | "Approved - Account Verification" |
| "86" | "PIN Validation Not Possible or Invalid PVK/ZPK/Offset/PVV" |
| "87" | "Approved - Purchase Only" |
| "88" | "Invalid Transaction (CVC1/CVV2/CID/iCVV Format Error)" |
| "89" | "Bad CVC1/iCVV/Expiry Date" |
| "91" | "Issuer or Switch Inoperative" |
| "92" | "Unable to Route Transaction" |
| "93" | "Transaction Cannot be Completed" |
| "94" | "Duplicate Transmission" |
| "96" | "Refer to Card Issuer / System Error" |
| "97" | "Already Activated Card" |
| "99" | "Approve Transaction in Super Green Path" |
| "AT" | "Auth-Host Timed Out" |
| "CD" | "Cryptogram Decline" |
| "CN" | "Invalid Currency" |
| "DN" | "Duplicate Record Found Against Name and DOB / Auth-Host Down" |
| "EX" | "Status inquiry / Account Verification declined due to invalid Card Expiry" |
| "E7" | "Bad CVV2/CID/Expiry Date" |
| "GA" | "General AVS Decline" |
| "GC" | "General Card Decline" |
| "GV" | "General CVV2 Decline" |
| "PA" | "Card is Pre-Active" |
| "PF" | "Purse Found with Invalid Status" |
| "PI" | "PIN Change Fail Invalid Data" |
| "PL" | "Bad PIN (Invalid PIN Block Length)" |
| "SA" | "Inactive Card" |
| "SD" | "Account Closed" |
| "SX" | "Status inquiry / Account Verification declined due to invalid Card Status" |
| "TM" | "Card Technology Mismatch" |
| "TR" | "Token Provisioning/Authorization Request declined with Red Path" |
| "X1" | "Bad AVS" |
| "1A" | "Strong Customer Authentication Required" |
| "AI" | "ATC Validation Failed (Authorization Host must set response code AI in case of ATC validation failure at authorization host side)" |
Terminal Input Capability Indicators
| Terminal Input Capability Indicator | Description |
|---|---|
| "00" | "Unknown" |
| "01" | "Manual, no terminal" |
| "02" | "Magnetic stripe" |
| "03" | "Bar code" |
| "04" | "OCR" |
| "05" | "ICC" |
| "06" | "File" |
| "07" | "Contact-less read capability via Mag stripe rules" |
| "08" | "Contact-less read capability via Chip rules" |
| "09" | "Mag stripe reader and key entry/Terminal does not read card data" |
| "10" | "Mag stripe reader and key entry and EMV-Compatible ICC reader" |
| "11" | "Contact-less M/Chip (Proximity Chip) Terminal supports PayPass M/Chip and PayPass mag-stripe transactions. The terminal also may support contact transactions; however, this value must only be used for Contact-Less Transactions." |
| "12" | "EMV specification (compatible chip reader) and magnetic stripe reader. This terminal can also support contact-less transactions; however, these values must only be used for contact transactions." |
| "13" | "Key entry only" |
| "14" | "EMV specification (compatible chip reader) only. This terminal can also support contactless transactions; however, this value must only be used for contact transactions." |
| "15" | "MICR read (POS Check Service), U.S. Only" |
| "16" | "MICR read and image-capable (POS Check Service), U.S. Only" |
| "17" | "Terminal does not read card data" |
| "18" | "Radio Frequency Identification (RFID)" |
| "19" | "Secure Electronic Transaction (SET) with certificate" |
| "20" | "SET without certificate" |
| "21" | "Channel-encrypted Electronic Commerce Transaction (SSL)" |
| "22" | "Non-secure Electronic Commerce Transaction" |
| "23" | "Mobile Device" |
| "24" | "F (No Value)" |
| "25" | "Secure Cardless Entry" |
Terminal Type Codes
| Terminal Type Code | Description |
|---|---|
| "00" | "Administrative terminal" |
| "01" | "POS terminal" |
| "02" | "ATM" |
| "03" | "Home terminal" |
| "04" | "ECR" |
| "05" | "Dial terminal/ Call Center Operator" |
| "06" | "Fuel machine / Travelers Check Machine" |
| "07" | "Fuel Machine" |
| "08" | "POS script machine" |
| "09" | "Coupon machine" |
| "10" | "Ticket machine" |
| "11" | "Franchise teller / Point of Banking terminal" |
| "12" | "Personal banking" |
| "13" | "Public utility" |
| "14" | "Vending" |
| "15" | "Self - service" |
| "16" | "Authorization" |
| "17" | "Payment" |
| "18" | "VRU" |
| "19" | "Smart phone" |
| "20" | "Interactive television" |
| "21" | "Personal Digital Assistant(PDA) / Mobile Device" |
| "22" | "Screen phone" |
| "23" | "Electronic commerce" |
| "24" | "Transponder(IBM - only) / MICR terminals at POS(Tandem - only)" |
| "26" | "Off Premise" |
| "27" | "Not a CAT transaction" |
| "28" | "Authorized Level 1 CAT: automated dispensing machine with PIN or ATM" |
| "29" | "Authorized Level 3 CAT: limited amount terminal" |
| "30" | "Authorized Level 4 CAT: In - flight Commerce" |
| "31" | "Unspecified" |
| "32" | "Reserved" |
| "33" | "Unattended customer terminal" |
| "34" | "Travelers Check Machine" |
| "35" | "MICR terminal at teller" |
| "36" | "Internet Terminal" |
| "37" | "POS terminal allows partial pre - authorizations" |
| "38" | "Multimedia Terminal" |
| "39" | "Manual Transactions at Bank Counter" |
| "40" | "Personal Computer" |
| "41" | "Mobile Phone" |
| "42" | "I type fixed phone (Telephone without PIN pad)" |
| "43" | "II type fixed phone" |
| "44" | "Wireless POS" |
| "45" | "CDRS" |
| "46" | "Merchant’s Terminal" |
| "47" | "Setup Box" |
| "48" | "Batch File Processing System" |
| "49" | "Authorized Level 2 CAT" |
| "99" | "Unknown" |
Transaction Type Codes
| Transaction Type Code | Description |
|---|---|
| "00" | "Purchase" |
| "01" | "Withdrawal" |
| "02" | "Debit Adjustment" |
| "03" | "Guarantee with Conversion (POS Check Service) (Future Use)" |
| "04" | "Verification with Conversion (POS Check Service) (Future Use)" |
| "06" | "Traveler Check" |
| "09" | "Purchase with Cash Back" |
| "10" | "Account Funding" |
| "11" | "Quasi-Cash Transaction-Debit or Internet Gambling Transaction", |
| "12" | "Administrative Funds Debit" |
| "13" | "Funds Withdrawal for Electronic Purse / Address Verification with a goods or services Authorization for Recurring Billing (Recurring Payments)" |
| "14" | "Recurring Billing (Recurring Payments) - goods or services" |
| "15" | "Installment Payment - goods or Services" |
| "16" | "Paying for Subscription on a Regular Basis" |
| "17" | "Cash Disbursement" |
| "18" | "Deferred Goods and Services / Scrip Issue / Conversion Only (POS Check Service) (FutureUse) / Card Account Verification" |
| "19" | "Debit Fee Collection / Deferred Goods and Services With Cash Disbursement" |
| "20" | "Credit Return (of goods) / Credit Transaction / Credit Voucher or Merchandise / Return Authorization (U.S. Only) / Purchase Return/Refund" |
| "21" | "Deposit" |
| "22" | "Credit Adjustment" |
| "23" | "Check Deposit Guarantee" |
| "24" | "Check Deposit" |
| "25" | "Envelope-less Cash Deposit" |
| "26" | "Original Credit" |
| "28" | "Prepaid Activation and Load Prepaid Load / Payment Transaction" |
| "29" | "Credit Funds Disbursement / Primary Credit" |
| "30" | "Available Funds Inquiry / Commercial Deposit" |
| "31" | "Balance Inquiry" |
| "33" | "Account Updater Code / Account Verification (Future Use)" |
| "34" | "ATM Mini Statement" |
| "39" | "Eligibility Inquiry / Generic Balance Inquiry (Future Use)" |
| "40" | "Cardholder Account Transfer" |
| "44" | "Money Transfer" |
| "50" | "Bill Payment / Payment to Another Party" |
| "53" | "Payment (U.S. only)" |
| "54" | "Payment Debit (P2P)" |
| "55" | "Payment from Third Party" |
| "56" | "Payment Credit (P2P)" |
| "58" | "Payment from Account to Credit/Loan" |
| "59" | "Payment Enclosed" |
| "72" | "Prepaid Activation" |
| "91" | "PIN Unblock" |
| "92" | "PIN Change" |
| "BP" | "Bill Payment" |
| "DC" | "Chargeback Debit Adjustment" |
| "F1" | "Acquirer Charges" |
| "IT" | "International Funds Transfer (Debit)" |
| "VD" | "Value Added Services Debit" |
| "VC" | "Value Added Services Credit" |
| "VB" | "Value Added Service Balance Inquiry" |