# SCA Engage SSI Guide 1.0 ![](/files/efa4660844110ee230f74e3b7b9f59088275e04c) Reference Guide SCA Engage — Secure Services Interface Document Version 1.0 IMPORTANT NOTICE Verifone, the Verifone logo, MX Solutions, VX Evolution, and Engage are Trademarks and/or Registered Trademarks of Verifone, Inc., its subsidiaries or affiliates in the U.S. or in other countries. All other brand names and trademarks appearing in this publication are the property of their respective owners. NO WARRANTY The information contained in this publication is subject to change without notice. Although Verifone has attempted to ensure the accuracy of the contents of this publication, this publication may contain errors or omissions. The examples and samples are for illustration only. You should verify the applicability of any example or sample program before placing the software into productive use. This publication is supplied “as-is”. LIMITED LIABILITY In no event shall Verifone be liable for any indirect, special, incidental, or consequential damages including damages for loss of business, profits, or the like, even if Verifone or its representatives have been advised of the possibility of such damages. CONTACT INFORMATION Verifone, Inc. North America Development The Royal Center Four 11700 Great Oaks Way, Suite 210 Alpharetta, GA 30022 [www.verifone.com](http://www.verifone.com) Printed in the United States of America Copyright © 2023 Verifone, Inc. All rights reserved No part of this publication may be copied, distributed, stored in a retrieval system, translated into any human or computer language, transmitted in any form or by any means without prior written permission of Verifone, Inc. Revision History | Revision | Date | Author | Description | | -------- | ------------ | ----------- | ---------------------------------------------------------------------------------------- | | 1.0 | Mar 31, 2023 | ShatarupaR2 | Initial document created for Engage, based out on Point Secure Services Interface Guide. | Chapter 1 - Introduction This document is designed for developers and integrators interested in integrating Verifone Point Secure Commerce (SCA) device applications running on Verifone Engage devices, to any gateway or switch that can accept Point Secure Services Interface (SSI) messages. The purpose of this document is to: * Define an SSI interface to support integration of Point SCA device applications running on Verifone Engage devices to an SSI Listener using a common interface * Define the security protocol to establish and maintain the authenticity of messages between applications residing on Verifone devices and the SSI Listener Overview Verifone Point Secure Services Interface (SSI) enables merchants to process secure payment transactions in a real-time environment over the Internet and supports major payment types including credit, PIN-based debit, and gift/loyalty card transactions. Point SSI enables developers to integrate with any gateway or switch that can accept the SSI messages. Industry Types Point SSI supports the following industry types. * Retail and QSR (Quick Service Restaurant) * Restaurant (Table Service) *Future use* Payment Types Point SSI supports major payment types that are needed by today’s merchants. * Credit Cards – Point SSI supports credit card transaction processing for the following major credit cards: Visa, MasterCard, Discover, American Express, Diner’s Club, JCB, Google Wallet (card emulation payment) and Softcard (card emulation payment). * Debit Cards – Point SSI supports debit card transaction processing for both online (ATM) and offline debit cards. * EBT Cards – Point SSI supports EBT card transaction processing for both Cash Benefits and SNAP (Food Stamp) EBT cards. * Gift and Loyalty – Point SSI supports gift card and loyalty processing. * Merchandise Credit – Point SSI supports merchandise credit processing. * Private Label – Point SSI supports private label card transaction processing. * PayPal – Point SSI supports PayPal processing. * Checks – Point SSI supports paper check verification transactions. Entry Modes Point SSI supports the following entry modes. * Manual (Keyed Entry) * MSR * MSD Contactless * EMV Chip (Credit and Debit) * EMV Contactless (Credit card only) * EMV Quick Chip Card Features Point SSI supports the following credit card features. * AVS (Zip only) * CVV2 * Commercial Card (Level II) Transactions Supported Point SSI supports the following transactions. Administrative Transactions * Administration Packet – includes card type enablement by specific brand and supported transaction types. * EMV Download Initialization – transfers host data for EMV initialization parameters. * Parameter Download Initialization – transfers host data for Interac Debit initialization parameters. *For future use and is subject to change*. Credit Card Transactions * Authorization * Online (Pre-Authorization) - reduces cardholder’s limit; Capture required to place transaction into open batch. * Offline (Voice-Authorization) - places voice-authorized transaction into database only; Capture required to place into open batch. * Capture * Online (Sale) - reduces cardholder’s limit and places the transaction into the open batch. * Offline (Post Authorization) - places an approved voice-authorized transaction into the open batch. * Follow-on (Completion) - places an approved Authorization into the open batch or adjusts Capture. * Message Acknowledgment – acknowledges to the SSI Listener that a Sale was received by the POS. * Credit/Refund – returns funds to a cardholder’s account. * Void – removes a transaction from the open batch. * Add Tip (Restaurant only) – adds gratuity to a transaction in the open batch. *Future use.* * Reset Tip (Restaurant only) – removes gratuity from a transaction in the open batch. *Future use.* * Timeout Reversal – may be sent when an acknowledgement response is not received for a Sale or Pre-auth. * EMV Offline Approval Advice – used for EMV Credit Card Sales or Returns to be completed without connecting to issuer host. *EMV is in limited release.* * Last Transaction – report to determine the status of the last transaction processed. Debit Card Transactions * Sale - reduces cardholder’s limit and places the transaction into the open batch. * Message Acknowledgment – acknowledges to SSI Listener that the PIN Debit Sale was received by POS. * Refund – returns funds to cardholder’s account. Swipe and PIN required. * Void - removes transaction from open batch. Void not widely supported for debit. * Timeout Reversal – may be sent when acknowledgement not received. * EMV Offline Approval Advice – EMV Debit Sales/Returns without issuer connection. *Limited release.* * MAC Update – (Canadian Debit Only – Interac) – send MAC value and key pointer to host after MAC block update. *Future use.* * MAC Reversal – (Canadian Debit Only – Interac) – used when PIN pad fails to validate MAC block sent in host response. *Future use.* * Last Transaction - report used to determine last transaction status. EBT Card Transactions * Sale - reduces cardholder’s limit and places transaction into open batch. * Message Acknowledgment – acknowledges EBT Sale received by POS. * Return – returns funds to cardholder’s account. Swipe and PIN required. * Balance – verify amount of funds available in EBT account. * Timeout Reversal – may be sent when acknowledgement not received. * Last Transaction - report used to determine last transaction status. Gift Card and Merchandise Credit Transactions * Activate– activates and loads value on a new gift card. * De-activate – de-activates a gift card. * Increment (Add Value) - adds value to a gift card. * Redemption (Sale) – reduces cardholder’s limit and places transaction into open batch. * Message Acknowledgment – acknowledges Sale received by POS. * Void – removes transaction from open batch. * Balance Inquiry – returns gift card balance information. * Refund – returns value to cardholder’s account. * Gift Close – closes a gift card account. * Timeout Reversal – may be sent when acknowledgement not received. * Last Transaction - report used to determine last transaction status. Private Label Card Transactions * Authorization * Online (Pre-Authorization) * Offline (Voice-Authorization) * Capture * Online (Sale) * Offline (Post Authorization) * Follow-on (Completion) * Message Acknowledgment * Return * Reversal * Payment On Account * Last Transaction Check Transactions * Verify – paper check verification. * Sale – ACH sale. * Void - removes an ACH approved sale from open batch. * Reversal – reverse all or part of an ACH approved sale. PayPal Transactions * Check In * Check Out (Sale) * Void * Credit (Refund) Report Transactions * Daily Summary – summary report for each command type. * Pre-settlement – information on approved transactions since current batch opened. * Settlement Error – transactions that have not settled (terminal-based hosts). * Transaction Search – transaction details with filtering. * Settlement Summary – settlement summary information. * Last Transaction – status of the last transaction processed. * Duplicate Check - identifies similar transaction requests within date/time range. Other Transactions * Schedule Settlement – schedules settlement. * Token Query – retrieve token for a given card for identification or validate a return. Reference Documents * Point Application Parameters Guide (for your implementation) * Point Integration Guide (for your implementation) * Point SSI Sample Transactions Guide Definition of Terms The following terms and abbreviations are used throughout this document. | Term | Description | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | API | Application program interface | | Card Token | Card-based token, separate from CTROUTD or TROUTD, that is returned by the SSI Listener and sent up from SCA when available | | CTROUTD | SSI Listener-assigned unique identifier associated with a CLIENT\_ID’s transaction and related transactions | | Device | Payment acceptance device | | Gateway/Receiving gateway | Gateway or payment switch that accepts the SSI message specification (AKA SSI Listener) | | Interac Association | Canadian organization responsible for Interac Direct Payment (IDP) | | Interac Request String | String sent to PIN pad containing transaction-specific data for Interac flow | | MAC | Message Authentication Code – used for Canadian debit transaction integrity | | MAC Block | String data generated by the PIN pad and the processor | | POS | Point of Sale terminal or ECR | | SAF | Store and Forward | | SCA | Secure Commerce Application (Point application on Engage device) | | SSI | Secure Services Interface | | SSI Listener | Gateway/host accepting SSI messages (AKA SSI Provider) | | TROUTD | SSI Listener-assigned unique number associated with a transaction or series of related transactions | Chapter 2 – Security Device Key Authentication Authenticate to the SSI Listener via device management level, which uses a well-managed set of tokens. Additional detail can be found in Chapter 5 - Property Definitions. Managed Device Authentication The Verifone Secure Commerce Application (SCA) device application will authenticate to the SSI Listener via a managed set of tokens. This authentication uses a device key and is based on device serial number registration. Managed Device Authentication consists of the following four values: * CLIENT\_ID * SERIAL\_NUM * DEVTYPE * DEVICEKEY Note: You can use all four attributes; however, only two are configurable: CLIENT\_ID (your locator ID) and DEVICEKEY (authentication data). DEVTYPE and SERIAL\_NUM are taken from the device. CLIENT\_ID CLIENT\_ID maps to the merchant’s environment. It may represent account + site + terminal or store + lane depending on chosen granularity. CLIENT\_ID is generated/provided by the SSI Listener and downloaded to SCA on first contact registration. Example scenarios show how CLIENT\_ID can be composed (account+site+terminal or store+lane), with padding rules for SITE and TERMINAL or STORE and LANE. SERIAL\_NUM Device manufacture serial number (9 digits, no dashes). Required for authentication to identify transaction origin. DEVTYPE Device or application type. Determined by the application automatically. DEVICEKEY DEVICEKEY is a 64-byte token provided by the SSI Listener during registration. Masking must be used when displayed; typically only last 8 characters shown (others replaced with asterisks). Example masked: \*\*\*\*\*\*D5H1H6:o Admin Packet Registration and Resynchronization Device must be set up in SSI Listener first, then Admin packet runs afterward. This must be done prior to sending any transaction so the application retrieves the Device Key. If a key changes, request a new registration. First Admin Packet contains Serial Number and Device Type. Device retrieves Client ID and Device Key. Subsequent Admin packets must send Client ID, Serial Number, Device Type, and Device Key. Initial Admin Packet Registration Activate a Device After First Setup or After a Reset | Field | Value | Comments | | -------------- | ------------------ | ------------------------------------- | | FUNCTION\_TYPE | ADMIN | | | COMMAND | SETUP\_REQUEST\_V3 | | | SERIAL\_NUM | Ex: 123456789 | Manufacturer serial number (9 digits) | | DEVTYPE | Ex: P400 | Device Type | Example (XML-like): \[ P400 P400 169000704] Admin Packet Registration Response (Potential Fields) | Field | Value | Comments | | ------------------ | -------------------------------- | --------------------------------------------- | | CLIENT\_ID | Ex: 100010001 | Generated by SSI Listener. Unique per Device. | | DEVICEKEY | Ex: \*\*\*\*\*\*\*\*\*\*BAYrnyja | Generated by SSI Listener. | | SERIAL\_NUM | Ex: 123456789 | Manufacturer serial number | | DEVTYPE | Ex: P400 | Device Type | | STATUS | Ex: 1 | | | CARD\_TYPES | | Card Types Enabled/Disabled nodes | | TRANSACTION\_TYPES | | Transaction Types Enabled/Disabled nodes | Request sent to SSI Listener (example): P400 123456789 Response received from SSI Listener (example includes CARD\_TYPES, SUPPORTED\_FUNCTIONS, CLIENT\_ID, DEVICEKEY, STATUS). Subsequent Admin Packet Note: A re-Admin is triggered by the RSA attribute value “1” inside the RESPONSE tag of a transaction. Example RSA="1" indicates Re-Sync Admin (triggered by console change). Subsequent Admin packet must include CLIENT\_ID, SERIAL\_NUM, DEVTYPE, and DEVICEKEY. EMV Download Initialization EMV Parameter Download Request/response field definitions specify tags such as FUNCTION\_TYPE=PAYMENT, PAYMENT\_TYPE=CREDIT, COMMAND=EMVADMIN, CLIENT\_ID, SERIAL\_NUM, DEVTYPE, DEVICEKEY, DOWNLOAD\_STATUS, TROUTD (conditional). EMV Parameter Download Response Note: A maximum number of six public keys can be accepted from host at one time. Fields vary by processor. Keys are transferred in PUBLIC\_KEY\_\_n nodes; if more than six, DOWNLOAD\_STATUS=M indicates more keys to follow and SCA will send subsequent request with DOWNLOAD\_STATUS=S and TROUTD returned by host. Examples of initial request/response and subsequent request/response shown in XML-like format. Offline EMV Parameters INI files required for EMV are downloaded to the device. Point application parameter emvsetupreqd should be set to 1. Point consumes these INI files on load to perform EMV initialization. Files include: EMVTables.ini, CAPKData.INI, CTLSConfig.ini, OptFlag.ini. Other Parameters Download (Interac Debit) Request fields: FUNCTION\_TYPE=PAYMENT, PAYMENT\_TYPE=DEBIT, COMMAND=PARAM\_LOAD, CLIENT\_ID, SERIAL\_NUM, DEVTYPE, DEVICEKEY, DOWNLOAD\_STATUS (I/S/Y/F). Response fields (potential) include many INTERAC and device parameters, CARD\_PREFIX\_RANGE entries (up to 30), network control timers, device flags, TA K/TPK, etc. Example response given. Supported Card Encryption Encryption Type Valid values: * 0 - None * 1 - 3DES * 2 - DUKPT * 3 - PKI (TRACK\_DATA, ACCT\_NUM, CVV2 fields PKI encrypted) * 4 - Asymmetric * 5 - VSP (TRACK\_DATA, ACCT\_NUM, EXP\_MONTH, EXP\_YEAR fields VSP encrypted) VeriShield Protect (VSP) Optional VSP support for end-to-end protection using H-TDES™. Currently Track II is supported for POS terminals with Verifone Engage devices. SCA has native support for VSP. PKI Encryption Features: * RSA key lengths 1024 or 2048 bits * Validation checks on Track1/Track2/PAN per ISO standards * RSA public key stored in RSAPubKey.DAT (PEM format), key ID in RSAPubKey.DAT.ID * Encryption: OAEP padding + RSA public key, then base64-encoded for POS Note: Encrypted blob in ACCT\_NUM field may contain PAN, PAN|CVV, etc., depending on requested fields. 3DES with DUKPT Key Management * Data variant of key used * Key slot (e.g., ADE) * ECB or CBC modes; CBC IV choices: None / Zero / Random * Padding schemes: None / PKCS7 / X9.23 / ISO7816 * Data format choices for track/manual entry order Transport SSL Security * TLS 1.2 * Negotiated cipher suite(s) * Mime – text/xml Chapter 3 - Integration Guide Getting Started Connectivity / Registration / Authentication — refer to Device Key Authentication section. Integration Steps Perform four main steps to integrate using Point SSI. These are represented here as a stepper (each step dependent on prior): {% stepper %} {% step %} ### Accept the transaction request string * Accept the transaction request which opens and closes with a TRANSACTION tag. * The request consists of multiple XML tags within the TRANSACTION tag. * Required, Conditional, and Optional tags are documented in Chapter 4 – API Reference. * Tags may be in any order. Point SSI does not have an XML DTD or Schema. * Only one TRANSACTION per request. Build socket, send request, and tear socket down after each request. Example transaction: PAYMENT CREDIT SALE 100010001 099515396 P400 \*\*\*\*\*\*\*\*\*\*nvbkbhxy 542418\*\*\*\*\*\*1765 31405 12 14 1 1234567890123 5.00 DOE/JOHN 123 {% endstep %} {% step %} ### Stand up a listener (HTTPS POST) * Implement a listener that accepts secure HTTPS POST requests (TLS 1.2) with mime type 'text/xml'. * Ensure the cipher suite matches those negotiated per Transport SSL Security. {% endstep %} {% step %} ### Parse the request and generate response * Parse incoming XML and process the transaction via your gateway/host. * Return an XML response to the device according to the API reference. {% endstep %} {% step %} ### Generate the outcome of the transaction * Check TERMINATION\_STATUS first — if SUCCESS, transaction was processed by the SSI Listener (this does not mean approval). * Inspect RESULT and RESULT\_CODE to determine approval/decline. * RESPONSE\_TEXT may include processor/issuer messages (e.g., INSUFFICIENT FUNDS). * Store return values for reporting and follow-on transactions: TROUTD, AUTH\_CODE, RESULT, RESULT\_CODE, RESPONSE\_TEXT, CTROUTD. {% endstep %} {% endstepper %} Parse the request and return appropriate XML responses as defined in Chapter 4. Batch Settlement/Closure SSI supports BATCH SETTLE command; SSI Listener is responsible for batch segmentation, auto-settlement, host capture. SCA does not maintain batch information on the device; batch settlement data stored/maintained by SSI Listener. Close/settle your batch every day or it will be closed for you. Credit Cards Credit Card Features AVS * AVS compares cardholder address info for keyed transactions. Point SSI includes zip code entry for keyed transactions; SSI Listener returns AVS response. CVV2 * CVV2/CVC2/CID are used for card-not-present transactions; returned via SSI Listener response. Commercial Card (Level II) * Provide Level II data (TAX\_AMOUNT, CUSTOMER\_CODE, PURCHASE\_ID) for procurement/business cards to avoid downgrades. Credit Card Transaction Options FSA/HRA / IIAS * IIAS helps identify FSA/HRA-eligible items; merchants must pass FSA/HRA amounts with SALE/PRE\_AUTH using tags: * AMOUNT\_HEALTHCARE * AMOUNT\_PRESCRIPTION * AMOUNT\_VISION * AMOUNT\_CLINIC * AMOUNT\_DENTAL Example Full Approval/Capture of FSA Transaction shown with request and response XML. One Way Token (LPTOKEN) * Optional one-way token for card identifier; same value consistently for same card. Not acted upon by SCA. Duplicate Acceptance Level * Duplicate detection is the SSI Listener’s responsibility. To disable duplicate checking for a transaction, send FORCE\_FLAG=TRUE. Examples of duplicate detection response and manual override (FORCE\_FLAG=TRUE) shown. Partial Authorizations * To support partial auths, send PARTIAL\_AUTH=1 in SALE or PRE\_AUTH. SSI Listener may return DIFF\_AMOUNT\_DUE and APPROVED\_AMOUNT indicating authorized portion and remaining due. POS should prompt for remaining payment and submit new transaction for difference. Example partial auth request/response shown. Error Timeout Handling * SCA can send timeout reversals or send acknowledgements based on an 'ACK required' flag. See TIMEOUT\_REVERSAL and MESSAGE\_ACK. Store and Forward (SAF) * When SAF enabled and connectivity lost, device can locally approve transactions below floor limit until total limit reached. Stored transactions queued locally and sent when connection restored. * SAF process pings gateway with a HEAD request and expects HTTP 200 OK. Follow On Transactions * Responses include CTROUTD, INTRN\_SEQ\_NUM, and TROUTD (always); CARD\_TOKEN may be conditionally returned. * CTROUTD: Client-specific transaction identifier (per CLIENT\_ID) used for follow-ons (Voids, Credits, Tips, Completions). * INTRN\_SEQ\_NUM: SSI Listener-assigned sequence for each transaction; follow-ons get new values. * TROUTD: Transaction Routing ID for referencing prior transactions (REF\_TROUTD). CTROUTD Transactions * CTROUTD incremented per CLIENT\_ID. Returned in PAYMENT non-follow-on responses. Card Token * Card-based token may be returned for Sale and Pre-Auth transactions; can be used in later PRE\_AUTH/SALE/CREDIT. Implementing Follow On Transactions Recommended to store TROUTD and CTROUTD and maintain transaction status flags (voided/completed/tip added/settled). Provide POS UI to perform follow-ons. REF\_TROUTD Transactions * REF\_TROUTD used to reference card info from prior transaction; available only for credit card transactions and for commands Sale, Pre-Auth, Post-Auth. Other Features EMV Chip Cards * Device EMV settings determined through SCA; supported EMV schemes configured via SSI. Offline Floor Limit, Fallback Indicator, Public keys transferred from host. Two Way Card Token * Responses may contain two-way token in RESPONSE and requests may include token in REQUEST when known. Reports General Reporting via Point SSI * REPORT Function Type supports DAYSUMMARY, PRESETTLEMENT, SETTLEERROR, TRANSEARCH, SETTLESUMMARY, LAST\_TRAN, DUPCHECK, CUTOVER, SITETOTALS. * Some reports may be inaccurate for auto-close accounts with host-based processors. Report Types * Daily Summary: summary per command type with counts, totals, tip totals, cashback totals. * Pre-Settlement: info on transactions approved since current batch opened. * Settle Error: transactions that have not settled (not available for host-based processors). * Transaction Search: detailed output similar to Store Portal Transaction Detail; filtering supported. * Settlement Summary: summary info for a settlement date. * Last Transaction: status of most recent transaction for a device. * Duplicate Check: identifies similar transaction requests. * Cutover: device totals for batch close. * Site Totals: device totals associated with a site for batch close. REPORT Function Type * Input tags required for reports: FUNCTION\_TYPE=REPORT, COMMAND (one of report commands), CLIENT\_ID, SERIAL\_NUM, DEVTYPE, DEVICEKEY, MAX\_NUM\_RECORDS\_RETURNED, FORMAT (xml), DELIMITER, RETURN\_FLD\_HDRS, RESPONSEFIELDS, SEARCHFIELDS. Detailed request/response field tables for Daily Summary/Presettlement, Settle Error, Transaction Search, Settlement Summary, Last Transaction, Duplicate Check, Cutover, Site Totals are included in the API (see Chapter 4 for specifics). Chapter 4 – API Reference RETAIL Credit Card Requests (Retail Business) Credit Sale (SALE) * SALE reduces cardholder limit and places transaction into open batch. * Can be processed via ACCT\_NUM+EXP\_MONTH+EXP\_YEAR or TRACK\_DATA or REF\_CTROUTD or CARD\_TOKEN. Fields (required/conditional/optional) defined in a table for SALE. Example Retail Sale and Commercial Sale transactions provided, as well as EMV example. Credit Pre-Authorization (PRE\_AUTH) * PRE\_AUTH reduces cardholder limit but does not place transaction into open batch. COMPLETION required to place into open batch. * Can be processed via ACCT\_NUM+EXP\_MONTH+EXP\_YEAR or TRACK\_DATA or REF\_CTROUTD or CARD\_TOKEN. Fields defined; example provided. Credit Voice Authorization (VOICE\_AUTH) * Used to place Voice-Authorized transaction into SSI Listener database only; COMPLETION required to settle. * Fields defined; example provided. Credit Completion (COMPLETION) * Places an approved PRE\_AUTH or VOICE\_AUTH transaction into the open batch. Submit CTROUTD (or TROUTD). * Fields defined; example provided. Credit Post-Authorization (POST\_AUTH) * Places approved Voice-Authorization into open batch; used when settling on different date than voice-authorized. * Fields defined; example provided. Credit Return/Credit (CREDIT) * Used to refund funds to cardholder; typically used after batch has settled/closed. * Fields defined; can use ACCT\_NUM or TRACK\_DATA or CTROUTD or CARD\_TOKEN. * Example provided. Credit Void (VOID) * Removes SALE, CREDIT, POST\_AUTH, or COMPLETION from open batch (before settlement). Use CTROUTD (or TROUTD). * Fields defined; example provided. Signature Capture (SIGNATURE) * Add signature image info to SALE, POST\_AUTH, COMPLETION (follow-on). * Fields defined; request and response examples provided. Credit Message Acknowledgment (MESSAGE\_ACK) * Acknowledges Credit SALE, PRE\_AUTH, CREDIT, or VOID transaction was received by POS. * Fields defined; example provided. Credit Timeout Reversal (TIMEOUT\_REVERSAL) * Sent when acknowledgement response is not received for SALE or PRE\_AUTH. * Fields defined; example provided. EMV Offline Approval Advice (EMV\_ADVICE) * Used for EMV Credit Sales or Returns to be completed offline without connecting to issuer. * Fields defined. Dynamic Currency Conversion Card Rate (CARD\_RATE) * Sent to SSI host when BIN lookup indicates foreign card eligible for DCC. * Fields defined; example response provided. RESTAURANT-Specific Credit Card Requests Credit Add Tip (ADD\_TIP) and Credit Reset Tip (RESET\_TIP) * ADD\_TIP adds or adjusts gratuity prior to settlement. * RESET\_TIP removes gratuity. * Fields and examples provided. CREDIT Response * Response fields table listing AUTH\_CODE, AVS\_CODE, CTROUTD, CARD\_TOKEN, RESULT, RESULT\_CODE, TROUTD, LPTOKEN, and partial authorization fields APPROVED\_AMOUNT, DIFF\_AMOUNT\_DUE, AVAIL\_BALANCE, ORIG\_TRANS\_AMOUNT. * Example response provided. DEBIT Requests Debit Sale (SALE) * Requires PIN\_BLOCK and KEY\_SERIAL\_NUMBER and TRACK\_DATA; TRANS\_AMOUNT and other fields. * Example request provided. Debit Message Acknowledgment (MESSAGE\_ACK), Debit Void, Debit Return/Credit, Debit Timeout Reversal, EMV Offline Approval Advice * Fields and examples provided. Canadian Debit MAC Block Requests, MAC Update, MAC Reversal * Scenarios and request/response field details for MAC\_UPDATE and MAC\_REVERSAL. Debit Responses (Sale/Credit/Void, MAC Update, MAC Reversal) * Response field tables and examples provided. EBT Requests and Responses EBT Sale, Return (CREDIT), Balance, Message Acknowledgment, Timeout Reversal, Response fields with examples provided. GIFT and Merchandise Credit Requests and Responses Gift Redemption/Sale, Add Value, Void (Cancel), Activate, Credit, Close/Cash Out, Balance Inquiry, Message Acknowledgment, Timeout Reversal. Fields, rules, examples, and GIFT/Merch response fields and examples provided. PRIVATE LABEL Requests and Responses Private Label Sale, Pre-Auth, Voice Auth, Completion, Return, Reversal, Post Auth, Payment On Account, Message Acknowledgment, and Response fields. Examples included for request/response with receipt text. Token Query * TOKEN\_QUERY request/response to retrieve token for a given card. Fields and examples provided. PAYPAL Requests and Responses * Check In, Check Out (Sale), Void, Credit/Refund fields and responses documented, including required PAYMENT\_CODE and BATCH\_TRACE\_ID fields. CHECK Requests and Responses * Paper Check Verification, Check Sale, Check Void, Check Reversal, and corresponding response fields and examples. BATCH Request Settle / Close * Manual batch settlement: FUNCTION\_TYPE=BATCH, COMMAND=SETTLE with CLIENT\_ID, SERIAL\_NUM, DEVTYPE, DEVICEKEY. Example request/response provided. Chapter 5 - Property Definitions General Property Definitions * Definitions and constraints for CLIENT\_ID, COMMAND, DEVICEKEY, DEVTYPE, FUNCTION\_TYPE, LANE, PAYMENT\_TYPE, SERIAL\_NUM, STORE\_NUM. Payment Property Definitions * Detailed definitions for fields such as ABA\_NUM, ACCT\_NUM, ALT\_TAX\_ID, AMOUNT\_\* (HEALTHCARE, DENTAL, etc.), APR\_TYPE, AUTH\_CODE, BATCH\_TRACE\_ID, BILLPAY, BUSINESSDATE, CARDHOLDER, CARD\_TOKEN, CASHBACK\_AMNT, CASHIER\_NUM, CDD\_DATA, CHECK\_NUM, CHECK\_TYPE, CLERK\_ID, CMRCL\_FLAG, COL\_n, CREDIT\_PLAN\_NBR, CTROUTD, CUSTOMER\_\* fields, DCC\_\* fields, DEBIT\_TYPE, DL\_NUMBER, DL\_STATE, EBT\_\* fields, EMV\_REVERSAL\_TYPE, EMV\_TAGS, ENCRYPTION\_TYPE, EXP\_DATE, EXP\_MONTH, EXP\_YEAR, FORCE\_FLAG, GIFT\_SECURITY\_CODE, GIFT\_UNITS, INTERAC\_\* fields, INSTALLMENT, INVOICE, KEY\_SERIAL\_NUMBER, MICR, MIDDLENAME, MODIFIER, OC\_INDUSTRY\_CODE, ORDER\_DATETIME, ORIG\_PURCH\_DATE, ORIG\_TRANS\_DATE, ORIG\_TRANS\_TIME, PARTIAL\_AUTH, PAYEE, PAYMENT\_SUBTYPE, PAYPASS\_TYPE, PIN\_BLOCK, PIN\_CODE, PINLESS\_DEBIT, PRESENT\_FLAG, PROMO\_CODE, PURCHASE\_APR, PURCHASE\_ID, RECURRING, REFERENCE, REF\_TROUTD, RESPONSE\_TEXT, RETAIL\_ITEM\_DESC\_1, RETURNEMBOSSED, SAF\_FLAG, SERVER\_ID, SHIFT\_ID, SURCHARGE\_AMNT, TA\_FLAG, TA\_TOKEN, TABLE\_NUM, TAX\_AMOUNT, TAX\_IND, TIME, TIP\_AMOUNT, TKN\_PAYMENT, TKN\_PROCESS, TKN\_RENEW, TOR\_STATUS, TOT\_NUM\_CARDS, TRACK\_DATA, TRANS\_AMOUNT, TRANSACTION\_ID, TROUTD. EMV Request Data * EMV\_TAGS format TLV and examples. EMV Request Data (PKI Supplement) lists fields that are RSA-encrypted. Batch Property Definitions * BATCH\_NUM definition. Response Property Definitions * Definitions and examples for response fields: ACCT\_NUM, ACTION\_CODE, AMOUNT\_BALANCE, APPROVED\_AMOUNT, APR\_TYPE, AUTH\_CODE, AUTH\_RESP\_CODE, AVAIL\_BALANCE, AVS\_CODE, BANK\_USERDATA, BATCH\_NUM, BATCH\_TRACE\_ID, CARD\_TOKEN, CB\_AVAIL\_BALANCE, CMRCL\_TYPE, CREDIT\_PLAN\_NBR, CTROUTD, CVV2\_CODE, DIFF\_AMOUNT\_DUE, DUP\_\* fields, EMV\_TAGS\_RESPONSE, EMV\_UPDATE, ERR\_SEQ\_NUM, FS\_AVAIL\_BALANCE, HOST\_RESPCODE, INTRN\_SEQ\_NUM, INVOICE, LPTOKEN, MERCHID, ORIG\_TRANS\_AMOUNT, PAYMENT\_MEDIA, PAYMENT\_TYPE, PURCHASE\_APR, RECEIPT\_TEXT, REFERENCE, RESPONSE\_TEXT, RESULT, RESULT\_CODE, STATUS\_CODE, STATUS\_FLAG, SVC\_PHONE, TAK, TERMID, TERMINATION\_STATUS, TPK, TRACE\_CODE, TRANS\_DATE, TRANS\_TIME, TRANS\_SEQ\_NUM, TROUTD, VSP\_\* fields. EMV Response Data * EMV\_TAGS\_RESPONSE in TLV format; example provided. DCC Response Data * Fields returned in CARD\_RATE response and meanings. Maximum Field Lengths table provided. Appendix A – VeriShield© * Overview, key benefits, process, Admin packet behavior for VSP, command examples, result codes (e.g., 4=CAPTURED, 092=TRX ENCRYPTED, NO TERMINAL KEYS, 904=NEW KEYS GENERATED). Appendix B – Pass Through Fields Overview * SCA can send pass-through fields between SCI and SSI configured using scaPassThrgFields.INI in /home/usr1/flash. REQUEST and RESPONSE sections define tags to pass through. Requires Verifone SE and MX SCA 2.19.24+. INI Format Rules * REQUEST section: tag=\,\,\,\,\ * VAL\_TYPE: 1=Singleton, 2=String, 4=Boolean, 7=Numerics * RESPONSE section: tag=\ (fields passed through as-is) Example scaPassThrgFields.INI provided. *** Notes and conversions applied for GitBook: * The original Table of Contents / navigation block has been removed. * The numbered Integration Steps were converted into a stepper for better step-by-step representation. * All original links, examples, and XML snippets retained as-is (no modification of URLs or examples). * No new information was added; content preserved and restructured per GitBook advanced block rules. If you want, I can: * Convert specific repeated large tables into card or columns blocks for improved readability. * Create tabs for sample requests/responses per payment type. * Extract and create a quick-reference summary card table (e.g., common commands and required fields). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.verifone.com/sca/tbd-documentation/sca-engage-ssi-guide-1.0.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.