# SCA Mobile Wallet Setup Guide 2.0 ­ ![new verifone](/files/b9912f1fe48eaa7f6a8eda24edbbea660964ddaa) **Setup Guide** **SCA Mobile Wallet VAS** Document Version: 2.0 **COPYRIGHT** IMPORTANT NOTICE Verifone, the Verifone logo, VeriCentre, SoftPay, Omni, NURIT, VeriShield Protect, Vx Solutions, VX Evolution, SC, MX Solutions, and Engage are trademarks of Verifone, Inc. in the United States or 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 © 2019 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, or transmitted in any form or by any means without prior written permission of Verifone, Inc. *** **REVISION HISTORY** | Revision | Date | Author | Revision Description | | -------- | -------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | 2.0 | 05/30/19 | ShatarupaR2 | Changed the document format, like header, footer style, chapter headings, sub headings, tables and other content alignments for consistency. | | 1.0 | 08/02/18 | CatherineP1 | Initial release | Table of Contents [Introduction 1](#_Toc10113387) [Document Overview 1](#_Toc10113388) [Document Audience & Objective 1](#_Toc10113389) [Using this Document 1](#_Toc10113390) [Terms 2](#_Toc10113391) [Data Types & Rules 3](#_Toc10113392) [Overview 4](#_Toc10113393) [Mobile Wallet VAS Features 5](#_Toc10113394) [One-Tap 5](#_Toc10113395) [Two-Tap 5](#_Toc10113396) [Auto-Presentment 5](#_Toc10113397) [Mobile Wallet Auto-Enrollment 5](#_Toc10113398) [Card and Payment Types 5](#_Toc10113399) [Primary Components 6](#_Toc10113400) [Encryption Keys 6](#_Toc10113401) [VSS Script ID & Slot 6](#_Toc10113402) [VSS Script for Wallet Keys 6](#_Toc10113403) [Wallet Key json File (\*.wky) 7](#_Toc10113404) [Terminal json File 7](#_Toc10113405) [CXPI json File 7](#_Toc10113406) [Prerequisites 8](#_Toc10113407) [VAS Transaction Overview 8](#_Toc10113408) [Software 9](#_Toc10113409) [Software Components for Engage Devices 9](#_Toc10113410) [Software Descriptions 9](#_Toc10113411) [Hardware 10](#_Toc10113412) [Supported Today 10](#_Toc10113413) [Supported Coming Soon 11](#_Toc10113414) [Terminal Capability Options 12](#_Toc10113415) [VAS or Payment 12](#_Toc10113416) [VAS & Payment 12](#_Toc10113417) [VAS Only 12](#_Toc10113418) [Payment Only 12](#_Toc10113419) [Integration 12](#_Toc10113420) [Processing SCA XML Tags 13](#_Toc10113421) [SCA Platform Components 13](#_Toc10113422) [SCA Terminal Modes 14](#_Toc10113423) [VAS Commands 15](#_Toc10113424) [Using VAS\_COMMANDS Apple VAS 2.0 Example VAS Only 15](#_Toc10113425) [Using NFCVAS\_MODE Apple VAS 2.0 Example VAS Only 15](#_Toc10113426) [VAS Only 15](#_Toc10113427) [VAS or Pay 16](#_Toc10113428) [Payment Only 17](#_Toc10113429) [Configuring Wallet Support 18](#_Toc10113430) [Updates 18](#_Toc10113431) [Request & Response 19](#_Toc10113432) [Request Sent 19](#_Toc10113433) [Decrypted Response 19](#_Toc10113434) [Decrypted Pass 19](#_Toc10113435) [SCA Wallet json File 20](#_Toc10113436) [Setting Merchant Index and/or VAS Terminal Mode 21](#_Toc10113437) [POS Ability to Set VAS Terminal Mode during START SESSION 21](#_Toc10113438) [POS Ability to Set VAS Terminal Mode during AUTH or CAPTURE 21](#_Toc10113439) [VAS Data Included in AUTH or CAPTURE Response 22](#_Toc10113440) [Flow when Consumer Taps Phone with Both VAS/Reward & Payment 23](#_Toc10113441) [Apple VAS 2.0 25](#_Toc10113442) [Product Name References 25](#_Toc10113443) [Sample Sale Commands 25](#_Toc10113444) [Apple VAS 2.0 Request 25](#_Toc10113445) [Apple VAS 2.0 Response 26](#_Toc10113446) [Google Smart Tap 2.1 Request 27](#_Toc10113447) [Google Smart Tap 2.1 Response 27](#_Toc10113448) [Rewards Provisioning 28](#_Toc10113449) [CXPI json File for Apple VAS 2.0 28](#_Toc10113450) [Requesting Public, Private & Wallet Keys 29](#_Toc10113451) [Apple VAS Kernel Interface 31](#_Toc10113452) [Architecture 31](#_Toc10113453) [SW1 & SW2 31](#_Toc10113454) [VAS Wallet Configuration Parameters 32](#_Toc10113455) [Read VAS Wallet Configuration Parameters 33](#_Toc10113456) [VAS Wallet Dynamic Configuration Parameters 35](#_Toc10113457) [VAS Wallet PreLoad Configuration Parameters 36](#_Toc10113458) [VAS Wallet Response Format 37](#_Toc10113459) [Google Smart Tap 2.1 38](#_Toc10113460) [Product Name References 38](#_Toc10113461) [Sample Sale Command 38](#_Toc10113462) [Google Smart Tap 2.1 Request 38](#_Toc10113463) [Google Smart Tap 2.1 Response 39](#_Toc10113464) [Invoking Google json Preload 39](#_Toc10113465) [9F4E Geo Location 40](#_Toc10113466) [Loyalty Bounce-Back 41](#_Toc10113467) [Google Smart Tap 2.1 VAS Configuration 41](#_Toc10113468) [Google Decryption/Key Management 42](#_Toc10113469) [Requesting Public, Private & Wallet Keys 42](#_Toc10113470) [VWI VAS Kernel Interface 43](#_Toc10113471) [Architecture 44](#_Toc10113472) [SW 1 & SW2 44](#_Toc10113473) [Types 45](#_Toc10113474) [Service Types 45](#_Toc10113475) [Service Issuer 45](#_Toc10113476) [Expected Format 45](#_Toc10113477) [New Service Type 45](#_Toc10113478) [Usage Status 46](#_Toc10113479) [Update Operation 46](#_Toc10113480) [VWI VAS APDU Message Format 46](#_Toc10113481) [VWI VAS APDU - P2 Extension 47](#_Toc10113482) [VAS Wallet PreLoad/Dynamic Configuration Parameters 49](#_Toc10113483) [PreLoad/Dynamic json Objects 50](#_Toc10113484) [VAS Wallet Read Configuration Parameters 51](#_Toc10113485) [VAS Wallet Response Format 55](#_Toc10113486) [Appendix A - Sample Files 56](#_Toc10113487) [Apple CXPI json File 56](#_Toc10113488) [Google CXPI json File 57](#_Toc10113489) [Terminal json File 58](#_Toc10113490) [APPLE.wky File 59](#_Toc10113491) [GOOGLE.wky File 60](#_Toc10113492) [Appendix B - Key Order Forms 61](#_Toc10113493) [Apple Keys 61](#_Toc10113494) [Google Keys 62](#_Toc10113495) Introduction ### Document Overview #### Document Audience & Objective The objective of this document is to guide programmers through the process of acquiring keys, setting up, and using Apple VAS 2.0 and Google Smart Tap 2.1 mobile wallet on Verifone Engage devices. Additionally, this document includes the commands that a Point of Sale (POS) integrator will need to support along with examples. #### Using this Document As you use this document, you may encounter the following document conventions. The easily identifiable icons draw your attention to certain concepts. | 🛈 | NOTE | A note is important information that either helps to explain a concept or draws attention to ideas that should be kept in mind. We recommend that you carefully review the notes you encounter. | | -- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 💣 | WARNING | We **HIGHLY**recommend that you read **ALL**warnings. These warnings will help prevent serious issues from occurring. | | -- | ------- | --------------------------------------------------------------------------------------------------------------------- | #### Terms The following terms and abbreviations are used throughout this document. | **Term** | **Description** | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ADK | Application Development Kit | | APDU | Application protocol data unit: the communication unit between a smart card reader and a smart card | | CXPI | Combined XPI | | ECR | Electronic cash register | | EMV | Europay, MasterCard and Visa chip cards | | json | JavaScript Object Notation; a simple data interchange format | | KEK | Key encryption key | | KEKID | The ID associated to the KEK | | KBPK | Key block protection key | | Merchant Name | Also known as Collector ID for Google Smart Tap 2.1 | | MSR | Magnetic strip reader | | NFC | Near-field communication | | OS | Operating system | | Pass | Digital representation of information from cards that can contain images, barcode, and text. Store in consumers' Apple mobile wallet applications on their smart devices | | PLC | Private label card | | POS | Point of Sale -- a terminal or ECR | | QSR | Quick Service Restaurant | | Service | Digital representation of information from cards that can contain images, barcode, and text. Store in consumers' Google mobile wallet applications on their smart devices | | Smart Device | Any NFC-enabled device, such as a smartphone or smartwatch, used for payments and/or loyalty and VAS | | VAS | Value-added services, such as loyalty, gift cards, coupons, etc. | | VRK | VeriShield Remote Key | | VWI | Verifone Wallet Interface – a protocol to interface NFC transfer of value-added services data between the smart device & the payment terminal | | XPI | External PIN Pad Interface | | wky | Wallet Key File – the Wallet Key json file stored on the payment terminal | When referencing the product, use the Google Smart Tap 2.1 product name. However, when referencing the product within software code, use Google Pay (no space between before "Pay"). This document references Google Smart Tap 2.1 (for Android Pay / Google Pay). | 🛈 | NOTE | This platform name, Android Pay, is still being used from a programming perspective and will eventually be replaced with Google Smart Tap 2.1. Most end users and merchants will likely be more accustomed to the terms Android Pay or Google Pay. | | -- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | #### Data Types & Rules The following data types and rule definitions are used in this document. **Data Types** | Type | Description | Min | Max | | ---- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | B | Boolean (such as 1, 0 TRUE, FALSE, T, F, YES, NO) | N/A | N/A | | C | Character (alphanumeric) | Minimum number of characters | Maximum number of characters | | D | Date (YYYY.MM.DD) | N/A | N/A | | E | Base64 Encoded Data | N/A | N/A | | F | Floating point number (decimal) |

Format: D(C) D = minimum number of
digits left of decimal C = minimum number of
digits right of decimal

|

Format: D(C) D = minimum number of
digits left of decimal C = minimum number of
digits right of decimal

| | L | List (select from list of valid values | N/A | N/A | | N | Numeric | Minimum number of digits | Maximum number of digits | | S | Static value | N/A | N/A | | T | Time (00:00:00) | N/A | N/A | **Data Rules** | Rule | Description | | ---- | ------------------------------------ | | R | Required – required in all cases | | M | Mandatory – required in all cases | | O | Optional – required in no cases | | C | Conditional – required in some cases | Overview Apple VAS 2.0® and Google Smart Tap 2.1™ technology allows merchant loyalty and rewards programs to be hosted in their consumer's mobile wallets on their smart devices (any NFC-enabled device, such as a phone or watch, that can be used for payments). Apple calls their technology "VAS Protocol", and Google calls their technology "Smart Tap". Mobile Wallet technology links a pass (Apple) or service (Google) stored in a consumer's wallet app on their smart device to loyalty providers. This allows merchants to: * Integrate their customer's loyalty card data into a mobile pass * Personalize the shopping experience * Streamline the checkout experience * Send targeted offers and coupons to customers * Automatically enroll customers into a loyalty program during a purchase Figure 1 shows a high-level overview of Wallet VAS. ![](/files/14e6be86771df1af27d29580247e626d9763c238) Figure 1 Wallet VAS Overview ### Mobile Wallet VAS Features Verifone's mobile wallet technology provides VAS decryption support at the payment terminal and is VAS-certified by Apple and Google. #### One-Tap The one-tap method allows a consumer to tap their smart device on an NFC-enabled terminal one time to send their payment data and apply their loyalty cards, gift cards, coupons, and offers to make purchases. #### Two-Tap In the two-tap method, the consumer taps their smart device on an NFC-enabled terminal to send the VAS information first and then tap their smart device the second time to send the payment data. Merchants can also have smart tap set up to require two taps if offers will change the total transaction price, and they want customers to know the new total before they complete the payment. #### Auto-Presentment Loyalty information is stored as a pass/service in customers' mobile wallet applications. Customers can set default passes/services to use for loyalty and payment providers. This means, when a customer enters a store and has that store's loyalty card pass/service loaded into their mobile wallet app, that store's loyalty card will be the default card shown when presenting a smart device for payment and/or loyalty at that store. #### Mobile Wallet Auto-Enrollment This technology allows for a consumer who is not already enrolled into a loyalty program to receive a personalized pass/service invitation on their smart device. This allows the new loyalty customer to start earning rewards; however, they won't be able to use those earned rewards until they complete their enrollment into the loyalty program. #### Card and Payment Types Mobile Wallet VAS works with private label cards, loyalty/reward cards, gift cards, and coupons. ### Primary Components #### Encryption Keys Wallet VAS data is encrypted in the VAS response data from the user’s smart device to the payment device (PIN Pad), and that encrypted payload is then forwarded in the message response from the payment device to the POS. The payment application can decrypt specific data in the response message from the payment device to the POS once the payment device is loaded with the proper wallet key files. Both Apple VAS 2.0 and Google Smart Tap 2.1 use key management, a payment terminal feature, to authenticate the terminal and to encrypt the data. Verifone Key Services will install the service wallet keys and generate a key file name which will be added to the key database. Once added, a temporary key file name will be generated to be used for validation by the requester. Once the key is validated, then a key part number will be generated. Finally, a key is requested using the part number and the payment device's serial number. Verifone supports device-specific remote key loading. Verifone Key Services will be responsible for key generation and delivery of the Remote Keyload File via VRK. When submitting the key request, the correct script ID and slot ID must be provided. #### VSS Script ID & Slot The VAS data decryption uses VSS scripting for processing the key files. The VSS engine resides in the Vault and processes well-defined commands to handle the stored key data. The VSS script file must be signed with the device sponsor certificate and authenticated before execution. On the Engage devices, the VSS script is installed by the operating system. | Wallet Identifier | Script ID | Slot | | ----------------- | --------- | ---- | | Apple | 61 | 000 | | Google | 61 | 003 | | | IMPORTANT | VSS scripts for Wallet will remain on Mx and Engage devices. | | - | --------- | ------------------------------------------------------------ | #### VSS Script for Wallet Keys The VSS script required for processing the wallet key file is included in the payment application executable bundle. It is important that the application, including the VSS script, is loaded prior to loading the VRK payload and the wallet key (WKY) file; otherwise, the keys will not be processed. | 🛈 | NOTE | VSS scripts are a Verifone proprietary script language to implement non-standard schemes, such as loyalty programs for key management handling. VSS keys and scripts are isolated from the standard payment functionality on the terminal and cannot influence payment functions. VSS keys can only be used by the associated VSS script. | | -- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | #### Wallet Key json File (\*.wky) The Wallet Key json file is stored on the payment terminal. Apple uses one key per pass, and it can be the same key across multiple passes or a unique key per pass. Google uses one key to authenticate the terminal and to create a sessions key that is used for data decryption. For the payment application used on Engage devices, the wallet keys are stored in the flash directory (/home/user1/flash). When a new wallet key is generated, the organization responsible for generating the wallet key (key provider) will also be responsible for encrypting it with a Key Block Protection Key (KBPK), calculating the MAC data, and then encoding that data in a json file for loading to the payment device. The unique wallet key is generated per merchant using merchant\_name and is associated with the specific merchant identifier stored as Service Id for Apple VAS 2.0 and Merchant ID for Google Smart Tap 2.1. Private keys are stored on the payment terminal, while public keys are stored on the pass on the smart device. The Encryption KEK ID listed in the Wallet Key json file must match the Encryption KEK ID associated with the key file name provided by Verifone Key Services. The wallet key file is parsed and then sent to the VSS script for validation and decryption (using the new KBPK). Once validated, the key is stored securely in the terminal and used for decrypting the received pass data. For more information on wallet keys, please refer to *Appendix A, Sample Files,* *Apple\_Keys\_\_and*\_ Google Keys\_.\_ #### Terminal json File The Terminal json file is provided as part of the application package and includes a default set of parameters and the NFC preloads. Any users that make changes to this file should be familiar with the NFC architecture and settings. Please refer to *Appendix A, Sample Files,* . #### CXPI json File The CXPI json file is also provided as part of the application package and can be used as the base for building a customer-specific json file. Specific Wallet VAS kernel and customer data is defined in the CXPI json file, including the Service ID, which is the pass type identifier that is linked to a card in the smart device's wallet, and a unique URL which can be used for rewards provisioning when sending a notification for each merchant. Please refer to \_Appendix A, Sample Files\_for examples of these files. The current loyalty and offer interface support Apple VAS 2.0 and/or Google Smart Tap 2.1. The actual options presented to the customer are determined by the contents of the CXPI.json file mentioned above. If the /VAS\_Configuration/Targets array contains an entry with "Source": "AndroidPay" in it, then Google Smart Tap 2.1 will be enabled. Similarly, if that array contains an entry with "Source": "ApplePay" in it, then Apple VAS 2.0 will be enabled. ### Prerequisites To ensure your Mobile Wallet VAS is fully functional, you must edit the CAMCORE.INI file and: * Set the seventh byte of the OPTFLAG file to 1 to enable Mobile Support. Set the seventh byte of the OPTFLAG file to 1 to enable Mobile Support. If Mobile Support is turned off, VAS will not function properly, so ensure this flag is turned on * Set WALLET\_SUPPORT = 1 This variable is read at application startup and must be enabled for Wallet VAS data to be returned. You can also set this variable in the config.usr1 settings. * Set APPEND\_WALLETDATA = 1 This variable is read at application startup and when enabled, appends the Wallet VAS data to the payment data response in the C30 response message. You can also set this variable in the config.usr1 settings. If you don't use this parameter, you can still send a D28 command to retrieve the payment and VAS data. | 🛈 | NOTE | **For Mx and Vx devices:** There is a separate contactless kernel that needs to be installed. However, for Engage devices, the contactless kernel is part of the ADK. CAMCORE.INI must be signed and authenticated. | | -- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ### VAS Transaction Overview The VAS transaction consists of the following four major steps: * Technology Selection –occurs when the payment application enables the card read (RF Polling) * Wallet Selection – occurs when the smart device is presented and authenticated * Data Exchange – data is exchanged between the smart device and the payment terminal * Data Decryption – if the data exchange is successful and encrypted pass data is exchanged, the data will be decrypted, assuming all proper pieces are in place ### Software This section describes the required software components and versions for the supported hardware. #### Software Components for Engage Devices This list of software components shows the minimum required versions to implement Mobile Wallet VAS with Apple VAS 2.0 and/or Google Smart Tap 2.1. | Software Component | Software Version | | ------------------ | ---------------- | | Operating System | 30810600 | | ADK Version | 4.4.4.6-193 | | SCA Version | 4.0 | #### Software Descriptions This section describes the different software applications that are delivered in the software package. This list includes applications used by the payment application. * Verifone Operating System The Verifone Operating System (VOS2) controls the components on the Engage devices, such as the user interface, hardware ports, display, keypad, and card processing. It is the software that speaks to the lower-level hardware components. The operating system is loaded on the PIN Pad at manufacturing. We also include the OS in our deployment package to ensure the OS version running is the same version we used in our testing, since there can be a dependency on a feature implemented in a specific version. * Application Development Kit (ADK) ADK is a lower-level library layer that serves as a software foundation upon which the payment application runs. The ADK also provides the tools used to build the application components. This library handles the communication for hardware, EMV, and security. ### Hardware You can set up and use SCA Mobile Wallet VAS on the Engage devices shown in Figure 2, if the payment devices are using ADK 4.6.0. | | IMPORTANT | The PIN Pads must have more than 64 MB of RAM for Mobile Wallet VAS to work (for VHQ & ADK). | | - | --------- | -------------------------------------------------------------------------------------------- | #### Supported Today The following devices are supported today for SCA Mobile Wallet VAS use. ![](/files/bf2ef410bf8d1e4cd6aac86befe1e689f633a92f) Figure 2 Currently Supported Hardware #### Supported Coming Soon The following devices will be supported soon for SCA Mobile Wallet VAS use. ![](/files/7f9de7fe40bfcd071c61c8bb727e162d566ae4ad) Figure 3 Supported Hardware Coming Soon ### Terminal Capability Options The NFC kernel processes the mobile tap transaction based on the settings in the *Capabilities* element of the Terminal json file. Please refer to *Appendix A. Sample Files,* to see a sample file. #### VAS or Payment In this mode, often referred to as Single Mode, the behavior is dependent on the VAS transaction response and the NFC kernel that is used. | 🛈 | NOTE | With VWI VAS kernel (Google), when the AutoPay setting in the terminal json file is enabled (AutoPay = 1), the payment will be forced if, and only if, some error, such as communication, data, etc., occurred. | | -- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | #### VAS & Payment This is the default mode and is often referred to as Dual Mode. With this setting, once the VAS transaction is completed, the kernel continues to get payment data from the smart device. In most cases, even if the VAS transaction is unsuccessful, the kernel will continue to request for the payment data. | 🛈 | NOTE | With VWI VAS kernel (Google), when the AutoPay setting in the terminal json file is enabled (AutoPay = 1), the payment will be forced if, and only if, some error, such as communication, data, etc., occurred. | | -- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | #### VAS Only In this mode, only VAS data is transmitted. If you will be using this mode, please focus on the VAS commands detailed within this document. #### Payment Only In this mode, only payment data is transmitted. It is unlikely that this mode will be used in a VAS customer environment and will not be detailed in this document. If you will be using this mode, please follow the existing contactless payment flow working on most of the NFC-enabled Verifone payment terminals today. ### Integration When you are ready to begin integrating SCA Mobile Wallet VAS in your environment, please work closely with your Verifone sales and technical team members. They will work with you through setup, testing, and launch. If you encounter any non-Mobile Wallet VAS-related issues during this time, please follow your existing Verifone production support processes. Processing SCA XML Tags ### SCA Platform Components As Figure 4 and Figure 5 illustrate, the Engage solution uses common, re-usable building blocks deployed as one application, featuring: * Verifone ADK allows for single source across Verifone terminals * Common application for standalone and semi-integrated modes * Same host interface for standalone and semi-integrated modes * HTML for different screen sizes * Commerce Acceptance Module common across all Engage terminals * Handles all EMV processing for Contact and Contactless * Performs encryption processing * Performs all card interaction * Used in XPI * Transaction flow is the only difference between standalone and semi-integrated modes ![](/files/d895a19ab6bcc6c81514fa84ad6bb9db460a27ae) Figure 4 Engage Application Topology ![](/files/d9ead69cbdc742957bb0b499435305fca12d23c5) Figure 5 Secure Commerce Architecture ### SCA Terminal Modes The NFC kernel will process the mobile tap transaction based on the settings in the *Terminal Capabilities* section of the SCA Wallet json file. SCA supports the following four terminal modes with their assigned XML requests: * VAS or Payment (0000) * VAS & Payment (0001) * VAS Only (0002) * Payment Only (0003) ### VAS Commands VAS commands can be used in XML to communicate directly to the NFC kernel without being forced to use the standard SCA terminal modes. There are two ways to make the VAS request: VAS\_COMMANDS and NFCVAS\_MODE. If you are using the NFCVAS\_MODE commands, you don't not need to include the VAS\_COMMANDS portion in the request, because they perform the same task. #### Using VAS\_COMMANDS Apple VAS 2.0 Example VAS Only \PAYMENT\ CAPTURE \1.00\ \FALSE\ \ {"Preload\_Configuration":{"Configuration\_version":"1.0","Terminal":{"Terminal\_Capabilities":{"Capabilities":"VAS"},"PollTech":"AB","PollTime":15000,"Source\_List":\[{"Source":"ApplePay"}]},"Wallet":{"Cmd\_Opts":{"Cmd\_Type":"Get"},"Service\_Type\_List":\[{"Service\_Type":"ABCCoupon"}]}}} \ #### Using NFCVAS\_MODE Apple VAS 2.0 Example VAS Only \PAYMENT\ CAPTURE \1.00\ \0002\ \FALSE\ | | IMPORTANT | VAS \_COMMANDS will always take preference over NFCVAS\_MODE. | | - | --------- | ------------------------------------------------------------- | #### VAS Only **Apple VAS 2.0 Using VAS\_COMMANDS** \PAYMENT\ CAPTURE \1.00\ \FALSE\ \ {"Preload\_Configuration":{"Configuration\_version":"1.0","Terminal":{"Terminal\_Capabilities":{"Capabilities":"VAS"},"PollTech":"AB","PollTime":15000,"Source\_List":\[{"Source":"ApplePay"}]},"Wallet":{"Cmd\_Opts":{"Cmd\_Type":"Get"},"Service\_Type\_List":\[{"Service\_Type":"ABCCoupon"}]}}} \ **Apple VAS 2.0 Using NFCVAS\_MODE** \PAYMENT\ CAPTURE \1.00\ \0002\ \FALSE\ **Google Smart Tap 2.1 Using VAS\_COMMANDS** \PAYMENT\ CAPTURE \1.00\ \FALSE\ \ {"Preload\_Configuration":{"Configuration\_version":"1.0","Terminal":{"Terminal\_Capabilities":{"Capabilities":"VAS"},"PollTech":"AB","PollTime":15000,"Source\_List":\[{"Source":"AndroidPay"}]},"Wallet":{"Cmd\_Opts":{"Cmd\_Type":"Get"},"Service\_Type\_List":\[{"Service\_Type":"ABCCoupon"}]}}} \ **Google Smart Tap 2.1 Using NFCVAS\_MODE** \PAYMENT\ CAPTURE \1.00\ \0002\ \FALSE\ #### VAS or Pay **Apple VAS 2.0 Using VAS\_COMMANDS** \PAYMENT\ CAPTURE \1.00\ \0000\ \FALSE\ \ {"Preload\_Configuration":{"Configuration\_version":"1.0","Terminal":{"Terminal\_Capabilities":{"Capabilities":"Payment|VAS"},"PollTech":"AB","PollTime":15000,"Source\_List":\[{"Source":"ApplePay"}]},"Wallet":{"Cmd\_Opts":{"Cmd\_Type":"Get"},"Service\_Type\_List":\[{"Service\_Type":"ABCCoupon"}]}}} \ **Apple VAS 2.0 Using NFCVAS\_MODE** \PAYMENT\ CAPTURE \1.00\ \FALSE\ **Google Smart Tap 2.1 Using VAS\_COMMANDS** \PAYMENT\ CAPTURE \1.00\ \FALSE\ \ {"Preload\_Configuration":{"Configuration\_version":"1.0","Terminal":{"Terminal\_Capabilities":{"Capabilities":"Payment|VAS"},"PollTech":"AB","PollTime":15000,"Source\_List":\[{"Source":"AndroidPay"}]},"Wallet":{"Cmd\_Opts":{"Cmd\_Type":"Get"},"Service\_Type\_List":\[{"Service\_Type":"ABCCoupon"}]}}} \ **Google Smart Tap 2.1 Using NFCVAS\_MODE** \PAYMENT\ CAPTURE \1.00\ \0000\ \FALSE\ #### Payment Only **Apple VAS 2.0 Using VAS\_COMMANDS** \PAYMENT\ CAPTURE \1.00\ \0003\ \FALSE\ \ {"Preload\_Configuration":{"Configuration\_version":"1.0","Terminal":{"Terminal\_Capabilities":{"Capabilities":"PAYMENT"},"PollTech":"AB","PollTime":15000,"Source\_List":\[{"Source":"ApplePay"}]},"Wallet":{"Cmd\_Opts":{"Cmd\_Type":"Get"},"Service\_Type\_List":\[{"Service\_Type":"ABCCoupon"}]}}} \ **Apple VAS 2.0 Using NFCVAS\_MODE** \PAYMENT\ CAPTURE \1.00\ \FALSE\ **Google Smart Tap 2.1 Using VAS\_COMMANDS** \PAYMENT\ CAPTURE \1.00\ \FALSE\ \ {"Preload\_Configuration":{"Configuration\_version":"1.0","Terminal":{"Terminal\_Capabilities":{"Capabilities":"Payment"},"PollTech":"AB","PollTime":15000,"Source\_List":\[{"Source":"AndroidPay"}]},"Wallet":{"Cmd\_Opts":{"Cmd\_Type":"Get"},"Service\_Type\_List":\[{"Service\_Type":"ABCCoupon"}]}}} \ **Google Smart Tap 2.1 Using NFCVAS\_MODE** \PAYMENT\ CAPTURE \1.00\ \0003\ \FALSE\ ### Configuring Wallet Support You must install the packages in the order shown below: 1. OS 2. ADK 3. FONTS 4. CTLS 5. CAM+EMV 6. NAFG-LIB 7. PLATFORM 8. SOLUTION ### Updates When using SCA Mobile Wallet VAS, use VHQ to download any updated files. You may also use the MxDownloader application as well. ### Request & Response #### Request Sent | 🛈 | NOTE | In the examples below, "Source":"\*\*\*Pay" would be replaced with "Source":"ApplePay" or "Source":"AndroidPay". | | -- | ---- | ---------------------------------------------------------------------------------------------------------------- | \ {"Preload\_Configuration":{"Configuration\_version":"1.0","Terminal":{"Terminal\_Capabilities":{"Capabilities":"VAS"},"PollTech":"AB","PollTime":15000,"Source\_List":\[{*"Source":"\*\*\*Pay*"}]},"Wallet":{"Cmd\_Opts":{"Cmd\_Type":"Get"},"Service\_Type\_List":\[{"Service\_Type":"ABCCoupon"}]}}} \ #### Decrypted Response \*{*"Source":"\*\*\*Pay"\_,"Merchant\_Name":"VerifoneQA","Merchant\_Id":"Jenny8675309","Mobile\_App\_Version":"0100","Services":\[{"is\_encrypt":1,"Service\_ID":"pass.com.verifone.test.B","Service\_Type":"ABCCoupon","Status\_Word":"9000","VAS\_Data":"**42315f31323334353637**","encrypt\_vas\_data":"0950c0d950c046ad301f36a51b29dd57c720ccbbfcdd2f9a7e95c5237ec0ff595a5c43b5f825add621f56e48eb10f3f62d0ba12b82c72889183032d5cf4e152912f9","cipher\_time\_stamp":"1f05925b"}]}\ #### Decrypted Pass Take the VAS\_Data":"**42315f31323334353637**value and convert the hexadecimal to ASCII. In our example: B1\_1234567. ### SCA Wallet json File | 🛈 | NOTE | In the example below, "Source":"\*\*\*Pay" would be replaced with "Source":"ApplePay" or "Source":"AndroidPay". | | -- | ---- | --------------------------------------------------------------------------------------------------------------- | { "Preload\_Configuration" : { "Configuration\_version" : "1.0", "Terminal" : { "Terminal\_Capabilities" : { "Capabilities" : "Payment\&VAS" }, "PollTech" : "AB", "PollTime" : 15000, "Source\_List" : \[ { "Source" : "\*\*\*Pay" } ] }, "Wallet" : { "Cmd\_Opts" : { "Cmd\_Type" : "Get", "Auth\_Param" : 1, "Encr\_Param" : 1 }, "Service\_Type\_List" : \[ { "Service\_Type" : "BetaCoupon" }, { "Service\_Type" : "AlphaCoupon" }, { "Service\_Type" : "BetaCoupon" }, { "Service\_Type" : "ALL" } ] } ### Setting Merchant Index and/or VAS Terminal Mode #### POS Ability to Set VAS Terminal Mode during START SESSION Please refer to *Session Management, Start Request* in the *Point SCA Integration Guide – MX ADK Edition* for more information. | 🛈 | NOTE | VAS\_COMMANDS is preferred over NFCVAS\_MODE. If both are sent, NFCVAS\_MODE will be ignored. | | -- | ---- | --------------------------------------------------------------------------------------------- | | XML Tag | Rule | Type | Min | Max | Value(s) | Comments | | ------------- | ---- | ---- | --- | --- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | | NFCVAS\_MODE | O | L | 4 | 4 | 0000 – VAS or Payment 0001 – VAS and Payment (default) 0002 – VAS Only 0003 – Payment only | MX Solutions Devices Only (Wallet Provider) Overrides what is in Wallet.json configuration file | | VAS\_COMMANDS | O | C | | | | Pass-through of json Wallet commands from the VWI SDK referenced | #### POS Ability to Set VAS Terminal Mode during AUTH or CAPTURE Please refer to *Payment Transactions, Authorization Request* and *Capture Request* in the *Point SCA Integration Guide – MX ADK Edition* for more information. | 🛈 | NOTE | VAS\_COMMANDS is preferred over NFCVAS\_MODE. If both are sent, NFCVAS\_MODE will be ignored. | | -- | ---- | --------------------------------------------------------------------------------------------- | | XML Tag | Rule | Type | Min | Max | Value(s) | Comments | | ------------- | ---- | ---- | --- | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | NFCVAS\_MODE | O | L | 4 | 4 |

0000 – VAS or Payment 0001 – VAS and Payment (reward card
& payment, payment type could
be EMV contact or EMV CTLS,
if available) 0002 – VAS Only (only reward card
accepted) 0003 – Payment only

| Optional with Wallet Payment Overrides what is in Wallet.json configuration file | | VAS\_COMMANDS | O | C | | | | Pass-through of json Wallet commands from the VWI SDK referenced | #### VAS Data Included in AUTH or CAPTURE Response Please refer to *Payment Transactions, Authorization Response* and *Capture Response* in the *Point SCA Integration Guide – MX ADK Edition* for more information. | XML Tag | Type | Example(s) | Comments | | ------------------- | ---- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | LOYALTY\_VAS | B | 1 | Indicates Loyalty VAS data received from Wallet provider (MX devices)**NOTE:** Once loyalty data is returned, VAS option will not be enabled for the next CAPTURE request (within the session) | | FULL\_VAS\_RESPONSE | C | "Source": "Android Pay", "Version":"2.1.9", "MID": "Alpha", "Customer": {"Customer\_Id": "12345",...} ... } | Full VAS return data | **LOYALTY\_OFFERS Child Elements** These elements are sent when LOYALTY\_VAS = 1. Please note this is for MX devices only. | XML Tag | Type | Example(s) | Comments | | ---------------- | ---- | ------------------------------------------ | ------------------------------------ | | PUBLISHER | c | Wallet Provider | | | CUSTOMER\_EMAIL | | | | | CUSTOMER\_ID | | 1234567890 | | | OFFER\_LIST | | | Refer to *OFFER Child Elements* next | | CARD\_LIST | | | Refer to *CARD Child Elements* next | | LOYALTY\_PAYLOAD | c | 448DEC4C83939A50C5A4562B2612BDF1D3D44E9A98 | | **OFFER Child Elements** | XML Tag | Type | Example(s) | Comments | | ------------------ | ---- | ----------------------------- | ---------------------------------------------------- | | OFFER\_ID | C | MAR10 | | | OFFER\_TYPE | C | COUPON | | | OFFER\_DESCRIPTION | C | 10% off all purchase in March | | | OFFER\_STATUS | C | 9000 | Refer to\_SW1 &\_SW2 on page 31 for more information | **CARD Child Elements** | XML Tag | Type | Example(s) | Comments | | ------------ | ---- | -------------------- | -------------------- | | CARD\_TYPE | C | GIFT\_CARD | | | CARD\_ID | | 123456789 | | | CARD\_ISSUER | C | ABC DEPARTMENT STORE | | | NOTE | C | ABC GIFT CARD | | | CARD\_EXP | D | 01/01/20 | Card expiration date | | CARD\_PIN | N | 1234 | Conditional | | CARD\_CVC1 | N | 1234 | Conditional | #### Flow when Consumer Taps Phone with Both VAS/Reward & Payment If the consume taps both VAS and payment data on a CAPTURE/AUTH request, SCA will send back the VAS data and store the payment data. On the second CAPTURE/AUTH request, if the amount is unchanged or, if MSD tap, SCA will not prompt for payment data and will continue with the store payment data. Figure 6 illustrates this Mobile Wallet transaction flow. ![](/files/a7856f89d9edb22d98f8c2b7812a134a2b20d4f9) Figure 6 Transaction Flow Apple VAS 2.0 VAS data passed during a transaction will be encrypted; however, when that data reaches the payment terminal, the data is decrypted and offered by Verifone. The Apple VAS Kernel provides an interface to get VAS data, such as loyalty, coupons, offers, and gift cards and to also push redeemed services and new services back to the consumer's smart device via a pass. * If VAS read is successful, the VAS data is returned, and the transaction is complete * If VAS read returns an error, the kernel will continue and attempt to retrieve payment data, depending on the VAS mode used ### Product Name References When referencing the product, use the Apple VAS 2.0 product name. However, when referencing the product within software code, use ApplePay (no space between before "Pay"). ### Sample Sale Commands #### Apple VAS 2.0 Request \PAYMENT\ CAPTURE \1.00\ \0000\ \FALSE\ #### Apple VAS 2.0 Response \LOYALTY VAS DATA CAPTURED\ OK \-1\ \SUCCESS\ \{"Source":"ApplePay","Mobile\_App\_Version":"0100","Merchant\_Name":"MerchantABC","Merchant\_Id":"ABC","Services":\[{"is\_encrypt":0,"Service\_ID":"pass.com.merchantabc.nfctestpass","Service\_Type":"CouponABC,"Status\_Word":"6a83"},{"is\_encrypt":0,"Service\_ID":"pass.merchantabc.card.dev","Service\_Type":"CouponABC","Status\_Word":"6a83"},{"is\_encrypt":0,"Service\_ID":"pass.merchantabc.store.card","Service\_Type":"CouponABC","Status\_Word":"6a83"},{"is\_encrypt":1,"Service\_ID":"pass.com.verifone.test.B","Service\_Type":"CouponABC","Status\_Word":"9000","VAS\_Data":"416c706861315f31323334353637","encrypt\_vas\_data":"fe65014e36e3aa588e9cb2760596ff344a435c06d28bd9304437270a41119c2252df3aca3288605821eaa923441649c8a5d2298a852f268ee0d9aaec180175d0c8350a354a02","cipher\_time\_stamp":"20d847d6"}]}\ \1\ \ ApplePay \ \CouponABC\ \6a83\ \CouponABC\ \6a83\ \CouponABC\ \6a83\ \CouponABC\ \9000\ \ \ 9 #### Google Smart Tap 2.1 Request \PAYMENT\ CAPTURE \1.00\ \FALSE\ \ {"Preload\_Configuration":{"Configuration\_version":"1.0","Terminal":{"Terminal\_Capabilities":{"Capabilities":"VAS"},"PollTech":"AB","PollTime":15000,"Source\_List":\[{"Source":"AndroidPay"}]},"Wallet":{"Cmd\_Opts":{"Cmd\_Type":"Get"},"Service\_Type\_List":\[{"Service\_Type":"CouponABC"}, {"Service\_Type":"Loyalty"}]}}} \ #### Google Smart Tap 2.1 Response \LOYALTY VAS DATA CAPTURED\ OK \-1\ \SUCCESS\ \{"Format\_Version":"1.0","Source":"AndroidPay","Mobile\_App\_Version":"1","Merchant\_Name":"MerchantABC","Merchant\_Id":"12345678","Min\_App\_Version":"0","Max\_App\_Version":"1","Services\_List":\[{"Service\_Issuer":"Merchant Issued","Service\_Issuer\_Id":"79798","Services":\[{"Service\_Type":"Loyalty","Service\_Object\_Id":"17367387539872002865","Service\_Number":"324234234"}]}]}\ \1\ \ AndroidPay \ \Loyalty\ \ \ 10 ### Rewards Provisioning Apple VAS 2.0 uses Rewards Provisioning to let consumers choose to automatically present a rewards card during a purchase. Rewards Provisioning occurs in two scenarios: * In scenario one, a consumer is already enrolled into a loyalty program and has the pass in their mobile wallet, so they will receive an automatic notification of rewards available * In scenario two, the consumer is not already enrolled into a loyalty program, but they receive a personalized pass invitation on their smart device. This allows the new loyalty customer to start earning rewards; however, they won't be able to use those earned rewards until they complete their enrollment into the loyalty program \PAYMENT\ CAPTURE \1.00\ \FALSE\ \ {"Preload\_Configuration":{"Configuration\_version":"1.0","Terminal":{"Terminal\_Capabilities":{"Capabilities":"Payment\&VAS"},"PollTech":"ABF","PollTime":5000,"Source\_List":\[{"Source":"ApplePay"}]},"Wallet":{"Cmd\_Opts":{"Cmd\_Type":"Get","Auth\_Param":0,"Encr\_Param":0},"Service\_Type\_List":\[{"Service\_Type":"PaneraCoupon"}],"Push\_Data":{"Customer\_Data":\[{"Type":"DU","Value":"1234567"}]}}}} \ ### CXPI json File for Apple VAS 2.0 Apple VAS 2.0 generates a unique URL and Service ID for each merchant. The Service ID is a Pass identifier linked to the cards stored in the smart device's mobile wallet. The example below shows what you need to create a URL to get smart device notifications, such as gift, rewards, etc. "Service\_ID": "pass.com.apple.passman" "URL": "[www.merchant.com](http://www.merchant.com)" "Customer\_Data": \[ { "Type" : "DU", "Value" : "1234567" } ] Both the reader and the POS compute the complete URL using a function (FUNC) as shown below: FUNC = ('https\://' || <"URL"> || '/' || <"Value">) As illustrated in Figure 7, where: * '||' is the concatenation operator * Literal characters inserted into the output are shown within single quote marks * Values within angle brackets are replaced with their values ![](/files/767953492b8077054f183b5a7efbc07ace3224c9) Figure 7 Dynamic URL Creation When defining the services for Apple VAS 2.0, you must ensure that the Service\_ID matches the Merchant\_ID defined in the Wallet Key (\*.wky) file. The settings must match for decryption to occur. Dynamic Merchant URL maximum size defined by Apple is 64 bytes, consisting of: · ‘https\://’ prefix – constant 8 bytes· Base merchant URL – up to 35 bytes (defined by product)· ‘/’ separator - 1 byte· Customer Data - up to 20 bytes (defined by product) ### Requesting Public, Private & Wallet Keys The following is a high-level overview on how a merchant requests a public, private, and wallet keys from Apple. Please note this process will take a few days. See Figure 8 for an illustration of this process. 1. Merchant sends a request to Apple for a pass type identifier for their business. Alternatively, a merchant may ask their loyalty provider or some other IT resource to make this request. 2. Apple returns the pass type identifier to the merchant. The pass type identifier, also known as a Service ID, will be used within the CXPI.json file. The Service ID is a Pass identifier linked to the cards stored in the smart device's mobile wallet. 3. Merchant sends their merchant name, their newly acquired Apple pass type identifier, and the serial number of their payment terminals to their Verifone representative/account manager. 4. Verifone completes the internal processing using the merchant's name and pass type identifier to generate key IDs and serial numbers for the merchants. During this process, the private key (with a generated part number) will be used to generate keys for the serial numbers for the merchant's payment terminals. 5. Verifone will send an email to the merchant that includes the public key and the APPLE.wky file which will be wrapped within a TGZ file to load onto the payment terminals. 6. Finally, based on the payment terminal serial numbers provided by the merchant in step 3, Verifone will send a separate email to the merchant with the keys generated for those payment terminals. Refer to *Appendix A, Sample Files* for a sample key request form for Apple. The entity responsible for loading terminals will also need to: * Confirm the public key was added to the pkpass generated by the merchant * Confirm the Apple wallet key * Install the VSS Decrypt Lib * Ensure the BMX file is loaded onto terminal * Verify VSS Script ID is 61 and Slot is 000 * Update the Wallet.json file with the correct Service ID / URL for Apple * During installation, ensure the terminal's timezone matches the current local timezone * After setting the timezone, ensure the time/date on the terminal is set to the local time and date and is within 10 seconds of the smart device, or VAS decryption will fail. ![](/files/98419f058e080ebd2e9c8ef3496c793692a3cf63) Figure 8 Requesting Apple Public, Private & Wallet Keys ### Apple VAS Kernel Interface * Apple VAS 2.0 VAS kernel provides an interface to "Get" VAS services data such as loyalty, coupons, offers, gift cards, and so on. * Apple VAS 2.0 VAS kernel provides an interface to "Push" redeemed services back to the smart device, as well as offer new services to the customer. ### Architecture ![](/files/571ce12910a28ec9585a3ce3be46d84ee4657bb0) Figure 9 Apple VAS 2.0 VAS Kernel Architecture **Data Rules** | Rule | Description | | ---- | ---------------------------------------------------------- | | R | Required – required in all cases | | M | Mandatory – required in all cases | | O | Optional – required in no cases | | C | Conditional – will be included if configured and/or exists | #### SW1 & SW2 Application protocol data unit (APDU) response has a status word indicating successful or unsuccessful execution of the command. The response may contain a general status word as defined by "ISO/IEC 7816-4 - Identification cards - Integrated circuit cards – Part 4", or specific status words as provided in the table below. | Status Word (SW1 SW2) | Description | | --------------------- | ------------------------------------------- | | 90 00 | Success | | 6A 83 | VAS data not found | | 62 87 | VAS data not activated | | 6B 00 | Wrong P1, P2 | | 67 00 | Wrong length of command data field | | 69 84 | User intervention required on mobile device | | 6A 80 | Incorrect data in the command field | | 63 40 | Unsupported application version number | #### VAS Wallet Configuration Parameters | json Key | Data Rule | Ancestor | Value | Description | | -------------------------- | ----------------- | -------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------ | | "VAS\_Configuration" | M | N/A | "Targets" "Configuration\_version | Keeps json objects used to configure Apple wallet kernel | | "Configuration\_version" | O | "VAS\_Configuration" | "1.0" |

Configuration structure version
Default: "1.0"

| | "Targets" | M | "VAS\_Configuration" | "Source" | Array of sources (Wallets) and associated parameters. The parameters represented as a json objects | | "Wallet\_Confirg\_version" | | | | | | "protocol\_Name" | | | | | | "Protocol\_Version" | | | | | | "Services" | | | | | | "Cmd\_Opts" | | | | | | "Merchant" | | | | | | "CustomPollData" | | | | | | "timestamp\_diff" | | | | | | "Source" | M | "Targets" | Variable | Wallet application name: "ApplePay" | | "Wallet\_Config\_version" | O | "Targets" | "1.0" |

Configuration structure version
Default: "1.0"

| | "Protocol\_Name" | M | "Targets" | Variable | Protocol specification name: "applepay\_vas" | | "Protocol\_Version" | M | "Targets" | Variable | Protocol specification version (terminal side) | | "Services" | M | "Targets" | "Service\_Type" | Array of services and associated parameters. The parameters represented as a json objects | | | "Service\_ID" | | | | | | "Service\_Issuer" | | | | | | "URL" | | | | | | "Vas\_Filter" | | | | | "Service\_Type" | M | "Services" | Variable | Service type. The value that is used in configuration will be used in response | | "Service\_ID" | M | "Services" | Variable | Service identifier - string of digits | | "Service\_Issuer" | M | "Services" | Variable | Service issuer | | "URL" | M | "Services" | Variable | URL address associated with the service | | "Vas\_Filter" | O | "Services" | Variable | VAS Filter parameters | | "Cmd\_Opts" | O | "Targets" | "Cmd\_Type" | Command options | | "Cmd\_Type" | O | "Cmd\_Opts" | "Push"/"Get" | Command type. Default: "Get" | | "Merchant" | O | "Targets" | "Merchant\_Name" | Merchant-specific data | | "Merchant\_ID" | | | | | | "Merchant\_Name" | O | "Merchant" | Variable | Merchant Name | | "Merchant\_ID" | O | "Merchant" | Variable | Merchant identifier | | "CustomPollData" | O | "Targets" | Variable | Proprietary polling data | | "timestamp\_diff" | O | "Targets" | Variable | Maximum expected time difference between Terminal and smart device, no validation. Default: 10 seconds | #### Read VAS Wallet Configuration Parameters | json Key | Data Rule | Ancestor | Value | Description | | ------------------------- | ------------------------------------------------------------------------ | -------------------- | ----------------- | --------------------------------------------------------------------------------------------- | | "VAS\_Configuration" | M | N/A | "Source" | Returns configuration structure version and array of configured wallets | | "Protocol\_Name" | | | | | | "Protocol\_Version" | | | | | | "App\_ID" | | | | | | "CustomPollData" | | | | | | "Services" | | | | | | "Wallet\_Config\_version" | | | | | | "Configuration\_version" | | | | | | "Merchant" | | | | | | "Cmd\_Opts" | | | | | | "key\_list" | | | | | | "timestamp\_diff" | | | | | | "Pre\_Load" | | | | | | "terminal\_caps" | | | | | | "Source" | M | "VAS\_Configuration" | "ApplePay" | Wallet application name: "ApplePay" | | "Protocol\_Name" | M | "VAS\_Configuration" | "applepay\_vas" | Protocol specification name: "applepay\_vas" | | "Protocol\_Version" | M | "VAS\_Configuration" | Variable | Protocol specification version (terminal side) | | "App\_ID" | M | "VAS\_Configuration" | Variable | Application Identifier | | "CustomPollData" | O | "VAS\_Configuration" | Variable | Proprietary polling data | | "Wallet\_Config\_version" | O | "VAS\_Configuration" | "1.0" | Wallet-specific configuration format version | | "Configuration\_version" | O | "VAS\_Configuration" | "1.0" | General configuration format version for all wallets | | "Services" | O | "VAS\_Configuration" | "Service\_Type" | Array of services and associated parameters. The parameters represented as json objects | | "Service\_ID" | | | | | | "Service\_Issuer" | | | | | | "URL" | | | | | | "Vas\_Filter" | | | | | | "Service\_Type" | M | "Services" | Variable | Service type. Examples: "Coupon", "Loyalty" | | "Service\_ID" | M | "Services" | Variable | Service identifier | | "Service\_Issuer" | M | "Services" | Variable | Service issuer | | "URL" | M | "Services" | Variable | URL address associated with the service | | "Vas\_Filter" | O | "Services" | Variable | VAS Filter parameters | | "Cmd\_Opts" | M | "VAS\_Configuration" | "Cmd\_Type" | Command options. Not returned in version 1.1.2 | | "Cmd\_Type" | M | "Cmd\_Opts" | Variable | Command type. Examples: "Push", "Get" | | "Merchant" | O | "VAS\_Configuration" | "Merchant\_Name" | Merchant-specific data. Not returned in version 1.1.2 | | "Merchant\_ID" | | | | | | "Merchant\_Name" | O | "Merchant" | Variable | Merchant Name. Empty, if not configured | | "Merchant\_ID" | O | "Merchant" | Variable | Merchant identifier. Empty, if not configured | | "timestamp\_diff" | M | "VAS\_Configuration" | Variable | Maximum expected time difference between Terminal and Mobile, no validation. Default: 10 secs | | "Pre\_Load" | M | "VAS\_Configuration" | "true" or "false" | Indicates if PreLoad Configuration exists | | "key\_list" | O | "VAS\_Configuration" | Variable | Merchant id associated with the key | | Variable | key id | | | | | Variable | key type | | | | | Variable | key service type | | | | | Variable | timestamp | | | | | Variable | KEK key id | | | | | Variable | KEK encrypted Apple private key | | | | | "terminal\_caps" | O | "Targets" | "Payment\&VAS" | Terminal capable to perform both VAS and Payment transactions | | "Payment\|VAS" | Terminal capable to perform Payment transactions if no VAS data received | | | | | "Payment" | Terminal capable to perform Payment transactions only | | | | | "VAS" | Terminal capable to perform VAS transactions only | | | | #### VAS Wallet Dynamic Configuration Parameters | json Key | Data Rule | Ancestor | Value | Description | | ------------------------ | ------------------------------------------------------------------------ | ------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | "Dynamic\_Configuration" | M | N/A | "Configuration\_version" | Keeps an optional json objects used by the terminal on the next transaction only | | "Terminal" | | | | | | "Wallet" | | | | | | "Configuration\_version" | O | "Dynamic\_Configuration" | Variable | Configuration structure version | | "Terminal" | O | "Dynamic\_Configuration" | "Terminal\_Capabilities" | Keeps an optional json objects configuring Terminal parameters | | "PollTech" | | | | | | "PollTime" | | | | | | "Source\_List" | | | | | | "Terminal\_Capabilities" | O | "Terminal" | "Capabilities" | Keeps an optional json object with capabilities field | | "Capabilities" | O | "Terminal\_Capabilities" | "Payment\&VAS" | Terminal capable to perform both VAS and Payment transactions. Used as default | | "Payment\|VAS" | Terminal capable to perform Payment transactions if no VAS data received | | | | | "Payment" | Terminal capable to perform Payment transactions only | | | | | "VAS" | Terminal capable to perform VAS transactions only | | | | | "Source\_List" | O | "Terminal" | "Source" | Keeps list of acceptable sources(wallets) | | "Source" | O | "Source\_List" | Variable | Source name: "ApplePay" | | "PollTech" | O | "Terminal" | Variable | Keeps an optional json object configuring terminal to poll for "ABF"/"AB"/"AF"/"BF"/"A"/"B"/"F" technologies**NOTE:** Currently, Verifone supports AB only | | "PollTime" | O | "Terminal" | Variable | Polling time in milliseconds | | "Wallet" | O | "Dynamic\_Configuration" | "Cmd\_Type" | Keeps an optional json objects configuring command options | | "Auth\_Param" | | | | | | "Encr\_Param" | | | | | | "Cmd\_Opts" | O | "Wallet" | "Get" | Get VAS data from the smart device. Used as default | | "Push" | Push VAS data to the smart device | | | | | "Cmd\_Type" | O | "Cmd\_Opts" | "Get" | Get VAS data from the smart device. Used as default | | "Push" | Push VAS data to the smart device | | | | | "Auth\_Param" | O | "Cmd\_Opts" | Variable | Not supported | | "Encr\_Param" | O | "Cmd\_Opts" | Variable | Not supported | | "Service\_Type\_List" | O | "Wallet" | "Service\_Type" | List of services to be issued in next transaction | | "Service\_Type" | O | "Service\_Type\_List" | Variable | Service type. Examples: "Coupon", "Loyalty" | | "Push\_Data" | O | "Wallet" | "Customer\_Data" | Dynamic data to push to the mobile | | "Customer\_Data" | O | "Push\_Data" | "Type" | Keeps an optional json objects to process customer data through appropriate function | | "Value" | | | | | | "Type" | O | "Customer\_Data" | Variable | Indicating type of function for customer data. Example: "DU" is a dynamic URL function | | "Value" | O | "Customer\_Data" | Variable | Actual customer data | #### VAS Wallet PreLoad Configuration Parameters | json Key | Data Rule | Ancestor | Value | Description | | ------------------------ | ------------------------------------------------------------------------ | ------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------ | | "Preload\_Configuration" | M | N/A | "Configuration\_version" | Keeps an optional json objects to be merged with static configuration and used by the terminal | | "Terminal" | | | | | | "Wallet" | | | | | | "Configuration\_version" | O | "Preload\_Configuration" | Variable | Configuration structure version | | "Terminal" | O | "Preload\_Configuration" | "Terminal\_Capabilities" | Keeps an optional json objects configuring Terminal parameters | | "PollTech | | | | | | "PollTime" | | | | | | "Source\_List" | | | | | | "Terminal\_Capabilities" | O | "Terminal" | "Capabilities" | Keeps an optional json object with capabilities field | | "Capabilities" | O | "Terminal\_Capabilities" | "Payment\&VAS" | Terminal capable to perform both VAS and Payment transactions. Used as default | | "Payment\|VAS" | Terminal capable to perform Payment transactions if no VAS data received | | | | | "Payment" | Terminal capable to perform Payment transactions only | | | | | "VAS" | Terminal capable to perform VAS transactions only | | | | | "Source\_List" | O | "Terminal" | "Source" | Keeps list of acceptable sources(wallets) | | "Source" | O | "Source\_List" | Variable | Source name: "ApplePay" | | "PollTech" | O | "Terminal" | Variable | Keeps an optional json object configuring terminal to poll for "ABF"/"AB"/"AF"/"BF"/"A"/"B"/"F" technologies | | "PollTime" | O | "Terminal" | Variable | Polling time in milliseconds | | "Wallet" | O | "Preload\_Configuration" | "Cmd\_Opts" | Keeps an optional json objects configuring Wallet parameters | | "Service\_Type\_List" | | | | | | "Push\_Data" | | | | | | "Cmd\_Opts" | O | "Wallet" | "Cmd\_Type" | Keeps an optional json objects configuring command options | | "Auth\_Param" | | | | | | "Encr\_Param" | | | | | | "Cmd\_Type" | O | "Cmd\_Opts" | "Get" | Get VAS data from the smart device. Used as default | | "Push" | Push VAS data to the smart device | | | | | "Auth\_Param" | O | "Cmd\_Opts" | Variable | Not supported | | "Encr\_Param" | O | "Cmd\_Opts" | Variable | Not supported | | "Service\_Type\_List" | O | "Wallet" | "Service\_Type" | List of services to be issued in next transaction | | "Service\_Type" | O | "Service\_Type\_List" | Variable | Service type. Examples: "Coupon", "Loyalty" | | "Push\_Data" | O | "Wallet" | "Customer\_Data" | Dynamic data to push to the mobile | | "Customer\_Data" | O | "Push\_Data" | "Type" | Keeps an optional json objects to process customer data through appropriate function | | "Value" | | | | | | "Type" | O | "Customer\_Data" | Variable | Indicating type of function for customer data. Example: "DU" is a dynamic URL function | | "Value" | O | "Customer\_Data" | Variable | Actual customer data | #### VAS Wallet Response Format | json Key | Data Rule | Ancestor | Value | Description | | ---------------------- | --------- | -------- | --------------- | ----------------------------------------------------------------- | | "Source" | M | N/A | Variable | Wallet application name. Examples: "ApplePay" | | "Mobile\_App\_Version" | M | N/A | Variable | Protocol specification version (Mobile side) | | "Merchant\_Name" | M | N/A | Variable | Merchant Name. Examples: "ABC Store". Empty if not configured | | "Merchant\_ID" | M | N/A | Variable | Merchant Identifier. Examples: "ABC123". Empty if not configured | | "Services" | O | N/A | "Service\_Type" | Keeps an array of json object that represents service information | | "Service\_ID" | | | | | | "Status\_Word" | | | | | | "VAS\_Data" | | | | | | "is\_encrypt" | | | | | | "encrypt\_vas\_data" | | | | | | "cipher\_time\_stamp" | | | | | | "Service\_Type" | M | Services | Variable | Service type. Examples: "Blob" | | "Service\_ID" | M | Services | Variable | Service identifier | | "Status\_Word" | M | Services | Variable | SW1, SW2 status word | | "VAS\_Data" | M | Services | Variable | VAS data only if SW1SW2 = 9000 | | "Mobile\_Token" | O | Services | Variable | Mobile token data. Will be returned only if available | | "is\_encrypt" | M | Services | Variable | Indicates if "VAS Data" is encrypted or not | | "encrypt\_vas\_data" | O | Services | Variable | Holds the encrypted VAS message | | "cipher\_time\_stamp" | O | Services | Variable | Timestamp that prefix every decrypted VAS data | Google Smart Tap 2.1 Google encryption of VAS data requires that both the public and private keys match. Google refers to this function as 'key management'. * If VAS read is successful, the VAS data is returned, and the transaction is complete * If VAS read is unsuccessful and AutoPay is enabled, the kernel will continue and attempt to retrieve payment data, depending on the VAS mode used. If the mode is set to VAS only, the kernel will NOT continue to payment | 💣 | WARNING | Do not define the Service Types “ALL” or “All except PPSE” for Engage devices. A known issue exists with the OS which prevents both of these service types from functioning properly. Instead, define each of the individual Service Types required – Coupon, Loyalty, PLC, Gift, Wallet Customer, etc. | | -- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ### Product Name References When referencing the product, use the Google Smart Tap 2.1 product name. However, when referencing the product within software code, use Google Pay. This document references Google Smart Tap 2.1 (for Android Pay / Google Pay). Please note this platform name, Android Pay, is still being used from a programming perspective and will eventually be replaced with Google Smart Tap 2.1. Most end users and merchants will likely be more accustomed to the terms Android Pay or Google Pay. ### Sample Sale Command #### Google Smart Tap 2.1 Request \PAYMENT\ CAPTURE \1.00\ \0000\ \FALSE\ \ #### Google Smart Tap 2.1 Response \LOYALTY VAS DATA CAPTURED\ OK \-1\ \SUCCESS\ \{"Format\_Version":"1.0","Source":"AndroidPay","Mobile\_App\_Version":"1","Merchant\_Name":"MerchantABC","Merchant\_Id":"12345678","Min\_App\_Version":"0","Max\_App\_Version":"1","Services\_List":\[{"Service\_Issuer":"MerchantIssued","Service\_Issuer\_Id":"79798","Services":\[{"Service\_Type":"Loyalty","Service\_Object\_Id":"17367387539872002865","Service\_Number":"324234234"}]}]}\ \1\ \ AndroidPay \ \Loyalty\ \ \ 10 ### Invoking Google json Preload \PAYMENT\ CAPTURE \1.00\ \FALSE\ \ {"Preload\_Configuration":{"Configuration\_version":"1.0","Terminal":{"PollTech":"ABF","PollTime":5000,"Terminal\_Capabilities":{"Capabilities":"VAS","system":{"Standalone":0,"Semi\_integrated":0,"Unattended":0,"Online":0,"Offline":0,"MMP":1,"Compression":1},"UI":{"Printer":0,"Printer\_Graphics":0,"Display":0,"Images":0,"Audio":0,"Animation":1,"Video":1},"CVM":{"Online\_PIN":0,"CD\_PIN":0,"Signature":0,"No\_CVM":0,"Device\_Generated\_Code":0,"SP\_Generated\_Code":0,"ID\_Capture":1,"Biometric":1},"Check\_Out":{"Digital\_Receipt":0,"Service\_Issuance":0,"OTA\_POS\_DATA":1},"AutoPay":0,"Presigned\_Auth":0}},"Wallet":{"Cmd\_Opts":{"Cmd\_Type":"Push","Auth\_Param":0,"Encr\_Param":0},"Push\_Data":{"Service\_Status\_List":\[{"Service\_Object\_Id":"ABC123A1","Service\_Usage":{"Usage\_Status":"Success","Usage\_Title":"Usage\_Title-1","Usage\_Description":"Usage\_Description-1"},"Service\_Update":{"Update\_Operation":"Add Balance","Update\_Payload":150}}, {"Service\_Object\_Id":"ABC123A2","Service\_Usage":{"Usage\_Status":"Invalid value","Usage\_Title":"Usage\_Title-2","Usage\_Description":"Usage\_Description-2"},"Service\_Update":{"Update\_Operation":"Subtract Balance","Update\_Payload":40}}], "New\_Service\_List":\[{"New\_Service\_Type":"Receipt","Service\_Title":"Service\_Title-1","Service\_URL":" [www.Service\_URL.com/1](http://www.service_url.com/1)"},{"New\_Service\_Type":"Valuable","Service\_Title":"Service\_Title-2","Service\_URL":" [www.Service\_URL.com/2](http://www.service_url.com/2)"}]}}}} \ ### 9F4E Geo Location Google uses the 9F4E geo location tag to identify the physical location of the consumer's smart device. This allows merchants and other VAS providers to target consumers and offer location-based incentives and offers. See an example below where the Merchant Name is set to Beta Coupon. 4F (AID): A00000002501 9A (Trans Date): 160714 9C (Trans Type): 00 82 (App Interchange Profile): 1800 84 (DF Name): A000000025011001 5F25 (App Effective Date): 170801 5F2A (Trans Curr Code): 0840 5F2D (Language Pref): 656E ("en") 9F33 (Term Capabilities): E0E8C8 9F34 (CVM Results): 5E0300 9F1A (Term Country Code): 0840 9F09 (App Version Number): 0001000200000000000000000000000000000000 9F02 (Amount Auth): 000000001234 9F4E (Merch Name & Loc): 42657461436f75706fbe ("BetaCoupon") 9F39 (POS Entry Mode): 91 C3: 474F471C9FA00A014E9FA010477B22536F75726365223A22416E64726F6964506179222C22466F726D61745F56657273696F6E223A22312E30222C224D6F62696C655F4170705F56657273696F6E223A2231227D00 C31 Response Code: 21 9F4E (Merch Name & Loc): 42657461436f75706fbe ("BetaCoupon") ### Loyalty Bounce-Back Google Smart Tap 2.1 uses Loyalty Bounce-Back to send coupons or codes to a consumer's smart device after a customer has made a purchase. These coupons are generally only valid for a limited time, and their value is usually more significant than a regular coupon. Loyalty Bounce-Back encourages and incentivizes consumers to come back and make additional purchases. The following example is a secure PUSH command. {"Preload\_Configuration":{"Configuration\_version":"1.0","Terminal":{"PollTech":"ABF","PollTime":5000,"Terminal\_Capabilities":{"Capabilities":"Payment\&VAS","system":{"Standalone":0,"Semi\_integrated":0,"Unattended":0,"Online":0,"Offline":0,"MMP":1,"Compression":1},"UI":{"Printer":0,"Printer\_Graphics":0,"Display":0,"Images":0,"Audio":0,"Animation":1,"Video":1},"CVM":{"Online\_PIN":0,"CD\_PIN":0,"Signature":0,"No\_CVM":0,"Device\_Generated\_Code":0,"SP\_Generated\_Code":0,"ID\_Capture":1,"Biometric":1},"Check\_Out":{"Digital\_Receipt":0,"Service\_Issuance":0,"OTA\_POS\_DATA":1},"AutoPay":0,"Presigned\_Auth":0}},"Wallet":{"Cmd\_Opts":{"Cmd\_Type":"Push","Auth\_Param":0,"Encr\_Param":0},"Push\_Data":{"Service\_Status\_List":\[{"Service\_Object\_Id":"ABC123A1","Service\_Usage":{"Usage\_Status":"Success","Usage\_Title":"Usage\_Title-1","Usage\_Description":"Usage\_Description-1"},"Service\_Update":{"Update\_Operation":"Add Balance","Update\_Payload": "150"}},{"Service\_Object\_Id":"ABC123A2","Service\_Usage":{"Usage\_Status":"Invalid value","Usage\_Title":"Usage\_Title-2", "Usage\_Description":"Usage\_Description-2" },"Service\_Update":{"Update\_Operation":"Subtract Balance","Update\_Payload":"40"}}],"New\_Service\_List":\[{"New\_Service\_Type":"Receipt","Service\_Title":"Service\_Title-1","Service\_URL":"www\.Service\_URL.com/1" },{"New\_Service\_Type":"Valuable","Service\_Title":"Service\_Title-2","Service\_URL":"www\.Service\_URL.com/2"}]}}}} ### Google Smart Tap 2.1 VAS Configuration When defining the services for Google Smart Tap 2.1, be sure that the Merchant\_ID matches the Merchant\_ID (Collector ID) defined in the Wallet Key (\*.wky) file. The settings must match for decryption to occur. ### Google Decryption/Key Management #### Requesting Public, Private & Wallet Keys The following is a high-level overview on how a merchant requests a public, private, and wallet keys from Google. Please note this process will take a few days. See for an illustration of this process. 1. Merchant sends a request to Google for a collector ID for their business. Alternately, a merchant may ask their loyalty provider or some other IT resource to make this request. 2. Google returns the collector ID to the merchant. The collector ID, also known as a merchant ID, will be used within the CXPI.json file. The collector ID is a service identifier linked to the cards stored in the smart device's mobile wallet. 3. Merchant sends their merchant name, their newly acquired Google collector ID, and the serial number of their payment terminals to their Verifone representative/account manager. 4. Verifone completes the internal processing using the merchant's name and collector ID to generate key IDs and serial numbers for the merchants. During this process, the private key (with a generated part number) will be used to generate keys for the serial numbers for the merchant's payment terminals. 5. Verifone will send an email to the merchant that includes the public key and the GOOGLE.wky file which will be wrapped within a TGZ file to load onto the payment terminals. 6. Finally, based on the payment terminal serial numbers provided by the merchant in step 3, Verifone will send a separate email to the merchant with the keys generated for those payment terminals. Refer to *Appendix A, Sample Files* for a sample key request form for Google. The entity responsible for loading terminals will also need to: * Confirm the public key was added to the pkpass generated by the merchant * Confirm the Google wallet key * Install the VSS Decrypt Lib * Ensure the BMX file is loaded onto terminal * Verify VSS Script ID is 61 and slot is 003 * Update the CXPI.json file with the correct Merchant ID / URL for Google ![](/files/57272e5972922e47189a56f335bda389cbb76f4d) Figure 10 Requesting Google Public, Private & Wallet Keys ### VWI VAS Kernel Interface * VWI VAS Kernel provides an interface to Get VAS services data such as Loyalty, Coupons, Offers, Gift Cards, etc. * VWI VAS Kernel provides an interface to Push redeemed services back to the smart device as well as offer new services to the customer. ### Architecture ![](/files/4ceb058abd4ee9387a147df5171f53a40353b443) Figure 11 VWI VAS Architecture **Data Rules** | Rule | Description | | ---- | ------------------------------------ | | R | Required – required in all cases | | M | Mandatory – required in all cases | | O | Optional – required in no cases | | C | Conditional – required in some cases | #### SW 1 & SW2 APDU response has a status word indicating successful or unsuccessful execution of the command. The response may contain a general status word as defined by "ISO/IEC 7816-4 - Identification cards - Integrated circuit cards - Part4", or specific status words as provided in the table below. | Status Word (SW1 SW2) | Description | | --------------------- | ---------------------------- | | 90 00 | Successful processing | | 63 10 | More data is available | | 64 00 | Execution error | | 67 00 | Wrong data length | | 69 01 | Application ID not supported | | 69 81 | Function not supported | | 69 82 | Security condition not met | | 69 99 | Application not available | | 6A 82 | Application not installed | | 6x xx | TBD, per ISO 7816-4 | ### Types #### Service Types "ALL", "All except PPSE", "PPSE", "Loyalty", "Coupon", "Gift Card", "PLC", "Mobile Blob", "Healthcare Profile", "Cloud Based Wallet", "Wallet Customer" #### Service Issuer "Unspecified", "Merchant Issued", "Wallet Issued", "Manufacturer Issued" #### Expected Format "Unspecified", "ASCII", "UTF 8", "UTF 16", "Binary", "BCD", "Hex" #### New Service Type "Unspecified", "Valuable", "Receipt", "Survey", "Goods", "Signup" #### Usage Status "Unspecified", "Success", "Invalid format", "Invalid value" #### Update Operation "No Action", "Remove", "Set Balance", "Add Balance", "Subtract Balance", "Free", "Activate", "Deactivate", "Add", "Sync with host", "Auto Selection Enable", "Auto Selection Disable", "Update", "Cloud Based Transaction", "Display/Prompt", "Default" #### VWI VAS APDU Message Format | Code | Name | Size (Bytes) | Description | | ---- | --------------------- | ------------ | ----------------------------------------------------------------------------------------------- | | CLA | Class | 1 | Class of instruction | | INS | Instruction | 1 | Instruction code | | P1 | Parameter 1 | 1 | Instruction parameter 1 | | P2 | Parameter 2 | 1 | Instruction parameter 2 | | Lc | Length (communicated) | 1 | Length of data field in bytes. 0 means no data | | Data | Data | Variable | The command payload (as an NDEF Record) | | Le | Length (expected) | 1 | Maximum number of bytes expected in the data field of the response (0 means unknown, up to 254) | #### VWI VAS APDU - P2 Extension By default, P2=0 across all APDUs except when APDU level chunking enabled. If enabled, P2=1 will be set across all APDUs. When request with P2=1 is sent, smart device to reply with SW1SW2 = 0x6100. | json Key | Data Rule | Ancestor | Type | Value | Description | | ------------------------- | --------- | -------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | | "VAS\_Configuration" | M | N/A | json Object | "Configuration\_version" | Ancestor of VAS wallet configuration | | "Targets" | | | | | | | Configuration\_version" | O | "VAS\_Configuration" | String (ASCII) | "1.0" | Current version of configuration structure and format. Default is "1.0" | | "Targets" | M | "VAS\_Configuration" | Array | "Source" | Array of sources(Wallets) and associated parameters. The parameters are represented as json objects | | "Wallet\_Config\_version" | | | | | | | "Protocol\_Name" | | | | | | | "Protocol\_Version" | | | | | | | "Wallet\_App\_Version" | | | | | | | "APDU\_Max\_Len" | | | | | | | "Services" | | | | | | | "Cmd\_Opts" | | | | | | | "Merchant" | | | | | | | "AIDs" | | | | | | | Source" | M | "Targets" | String (ASCII) | "AndroidPay" | Wallet source name | | "Wallet\_Config\_version" | O | "Targets" | String (ASCII) | "1.0" | Wallet configuration version. Default value is "1.0" | | "Protocol\_Name" | M | "Targets" | String (ASCII) | "VWI\_Kernel" | Protocol specification name | | "Protocol\_Version" | M | "Targets" | String (ASCII) | Variable | Protocol specification version (Terminal side). String of positive numbers | | "Wallet\_App\_Version" | M | "Targets" | Integer | Variable | Supported mobile wallet application version | | "APDU\_Max\_Len" | O | "Targets" | Integer | Variable | Size of payload for APDU packet. Minimum: 1, Maximum: 255. Default: 255 | | "Cmd\_Opts" | O | "Targets" | json Object | "Cmd\_Type" | Command/Authentication/Encryption options | | "Auth\_Param" | | | | | | | "Encr\_Param" | | | | | | | "Cmd\_Type" | O | "Cmd\_Opts" | String (ASCII) | "Get" or "Push" | Get or Push data command. Default: "Get" | | "Auth\_Param" | O | "Cmd\_Opts" | Boolean | 0 - Disabled, 1 - Enabled | Enable/Disable authentication process. Default: 0 | | "Encr\_Param" | O | "Cmd\_Opts" | Boolean | 0 - Disabled, 1 - Enabled | Enable/Disable encryption/decryption process. Default: 0 | | "Merchant" | M | "Targets" | json Object | "Merchant\_Name" | Command/Authentication/Encryption options | | "Merchant\_Id" | | | | | | | "Merchant\_Store\_Code" | | | | | | | "Merchant\_Type" | | | | | | | "Terminal\_Id" | | | | | | | "Store\_Id" | | | | | | | "Merchant\_Generic\_Data" | | | | | | | "Merchant\_Phone" | | | | | | | "Merchant\_Name" | M | "Merchant" | String (ASCII) | Variable | Merchant name | | "Merchant\_Id" | M | "Merchant" | String (BCD) | Variable | Merchant ID. Must be 8-digit number | | "Merchant\_Store\_Code" | O | "Merchant" | String (ASCII) | Variable | Merchant Postal, Area, Store Code | | "Merchant\_Type" | O | "Merchant" | String (ASCII) | Variable | Merchant type/category | | "Terminal\_Id" | O | "Merchant" | String (ASCII) | Variable | Terminal ID | | "Store\_Id" | O | "Merchant" | String (ASCII) | Variable | Store ID | | "Merchant\_Generic\_Data" | O | "Merchant" | String (ASCII) | Variable | Merchant generic data | | "Merchant\_Phone" | O | "Merchant" | String (ASCII) | Variable | Merchant phone number | | "Services" | M | "Targets" | Array | "Service\_Type" | Array of Services and associated parameters. The parameters represented as json objects | | "issuer" | | | | | | | "Service\_Type" | M | "Services" | String (ASCII) | [Service Types](broken://pages/e0ae9aa1ba926a905b0b4e8c0c1dc9c644a7637b#subsec_vwi_vas_kern_service_types) | Service type. Examples: "Coupon", "Loyalty" | | "issuer" | O | "Services" | json Object | "Service\_Issuer\_Id" | Service issuer information | | "Service\_Issuer" | | | | | | | "Service\_Issuer\_Id" | M | "issuer" | String (number 0 - 4294967294) | Variable | Service issuer identifier | | "Service\_Issuer" | M | "issuer" | String (ASCII) | [Service Issuer](broken://pages/e0ae9aa1ba926a905b0b4e8c0c1dc9c644a7637b#subsec_vwi_vas_kern_service_issuer) | Service issuer name | | "AIDs" | O | "Targets" | Array | "aid" | Array of application ID's for secondary select | | "aid" | O | "AIDs" | String (ASCII) | Variable | Application ID' | #### VAS Wallet PreLoad/Dynamic Configuration Parameters | json Key | Data Rule | Ancestor | Type | Value | Description | | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | [PreLoad/Dynamic jSON objects](broken://pages/e0ae9aa1ba926a905b0b4e8c0c1dc9c644a7637b#subsec_adk_nfc_vas_prl_dyn) | M | N/A | json Object | "Configuration\_version" | Keeps an optional json object used by the terminal on the next transaction only | | "Terminal" | | | | | | | "Wallet" | | | | | | | "Configuration\_version" | O | [PreLoad/Dynamic jSON objects](broken://pages/e0ae9aa1ba926a905b0b4e8c0c1dc9c644a7637b#subsec_adk_nfc_vas_prl_dyn) | json Object | N/A | Current version of configuration structure and format. Please refer to "ADK-NFC Programmers Guide" | | "Terminal" | O | [PreLoad/Dynamic jSON objects](broken://pages/e0ae9aa1ba926a905b0b4e8c0c1dc9c644a7637b#subsec_adk_nfc_vas_prl_dyn) | json Object | N/A | Terminal configuration parameters. Please refer to ADK-NFC Programmers Guide | | "Wallet" | O | [PreLoad/Dynamic jSON objects](broken://pages/e0ae9aa1ba926a905b0b4e8c0c1dc9c644a7637b#subsec_adk_nfc_vas_prl_dyn) | json Object | "Cmd\_Opts" | Wallet dynamic data. | | "Service\_Type\_List" | | | | | | | "Push\_Data" | | | | | | | "Cmd\_Opts" | O | "Wallet" | json Object | "Cmd\_Type" | Keeps an optional json object configuring command options | | "Auth\_Param" | | | | | | | "Encr\_Param" | | | | | | | "Cmd\_Type" | O | "Cmd\_Opts" | String (ASCII) | "Get" | Get VAS data from the smart device | | "Push" | Push VAS data to the smart device | | | | | | "Auth\_Param" | O | "Cmd\_Opts" | Boolean | 0-Disabled, 1-Enabled | Enable/Disable authentication process | | "Encr\_Param" | O | "Cmd\_Opts" | Boolean | 0-Disabled, 1-Enabled | Enable/Disable encryption/decryption process | | "Service\_Type\_List" | O | "Wallet" | json Array | "Service\_Type" | List of services to be issued in next transaction | | "Service\_Type" | O | "Service\_Type\_List" | String (ASCII) | [Service Types](broken://pages/e0ae9aa1ba926a905b0b4e8c0c1dc9c644a7637b#subsec_vwi_vas_kern_service_types) | Service type. Examples: "Coupon", "Loyalty" | | "Push\_Data" | O | "Wallet" | json Object | "Customer\_Data" | Keeps an optional json object to be pushed to the smart device | | "Service\_Status\_List" | | | | | | | "New\_Service\_List" | | | | | | | "Transaction\_Data" | | | | | | | "Customer\_Data" | O | "Push\_Data" | json Array | "Type" | Objects to process customer data through appropriate function. May be used on "Push" or/and "Get" commands | | "Value" | | | | | | | "Type" | O | "Customer\_Data" | String (ASCII) | Variable | Indicating type of function for customer data. Example: "DU" is a dynamic URL function | | "Value" | O | "Customer\_Data" | String (ASCII) | Variable | Actual customer data. | | "Service\_Status\_List" | O | "Push\_Data" | json Array | "Service\_Object\_Id" | Array of services status objects per service. | | "Service\_Usage" | | | | | | | "Service\_Update" | | | | | | | "Service\_Object\_Id" | M | "Service\_Status\_List" | String (ASCII) (hex) | Variable | Service object ID. Expected value is a Hex string (i.e "1234567890ABCDE") | | "Service\_Usage" | O | "Service\_Status\_List" | json Object | "Usage\_Status" | Service usage parameters | | "Usage\_Title" | | | | | | | "Usage\_Description" | | | | | | | "Usage\_Status" | M | "Service\_Usage" | String (ASCII) | Variable | [Usage Status](broken://pages/e0ae9aa1ba926a905b0b4e8c0c1dc9c644a7637b#subsec_vwi_vas_kern_usage_status) | | "Usage\_Title" | O | "Service\_Usage" | String (ASCII) | Variable | Title of usage action | | "Usage\_Description" | O | "Service\_Usage" | String (ASCII) | Variable | Description of usage action | | "Service\_Update" | O | "Service\_Status\_List" | json Object | "Update\_Operation" | Service update parameters | | "Update\_Payload" | | | | | | | "Update\_Operation" | M | "Service\_Update" | String (ASCII) | Variable | [Update Operation](broken://pages/e0ae9aa1ba926a905b0b4e8c0c1dc9c644a7637b#subsec_vwi_vas_kern_update_operation) | | "Update\_Payload" | O | "Service\_Update" | Integer | Variable | Update action payload | | "New\_Service\_List" | O | "Push\_Data" | json Array | "New\_Service\_Type" | Array of new services | | "Service\_Title" | | | | | | | "Service\_URL" | | | | | | | "issuer" | | | | | | | "New\_Service\_Type" | M | "New\_Service\_List" | String (ASCII) | Variable | [New Service Type](broken://pages/e0ae9aa1ba926a905b0b4e8c0c1dc9c644a7637b#subsec_vwi_vas_kern_new_service_type) | | "Service\_Title" | M | "New\_Service\_List" | String (ASCII) | Variable | Title of the service | | "Service\_URL" | M | "New\_Service\_List" | String (ASCII) | Variable | Service URL | | "issuer" | O | "New\_Service\_List" | json Object | "Service\_Issuer\_Id" | Service Issuer Information | | "Service\_Issuer" | | | | | | | Service\_Issuer\_Id" | M | "issuer" | String (number 0-4294967294) | Variable | Service issuer identifier | | "Service\_Issuer" | M | "issuer" | String (ASCII) | [Service Issuer](broken://pages/e0ae9aa1ba926a905b0b4e8c0c1dc9c644a7637b#subsec_vwi_vas_kern_service_issuer) | Service issuer name | | "Transaction\_Data" | O | "Push\_Data" | json Object | "Date\_Time" | type: String (ASCII). Conditional-if configured | | "Merchant\_Name" | type: String (ASCII). Conditional-if configured | | | | | | "Merchant\_Info" | type: String (ASCII). Conditional-if configured | | | | | | "Terminal\_Id" | type: String (ASCII). Conditional-if configured | | | | | | "Store\_Id" | type: String (ASCII). Conditional-if configured | | | | | | "Acquirer\_Id" | type: String (ASCII). Conditional-if configured | | | | | | "Trans\_Id" | type: String (ASCII). Conditional-if configured | | | | | | "Trans\_Status" | type: String (ASCII). Conditional-if configured | | | | | | "Trans\_Type" | type: String (ASCII). Conditional-if configured | | | | | | "Amount\_Pre\_Discount" | type: Number. Integer only, no floating point permitted. Conditional-if configured | | | | | | "Final\_Amount" | type: Number. Integer only, no floating point permitted. Conditional-if configured | | | | | | "Trans\_Currency\_Code" | type: String (ASCII). Conditional-if configured | | | | | | "Trans\_Currency\_Exp" | type: String (ASCII). Conditional-if configured | | | | | | "Type\_Of\_Goods" | type: String (ASCII). Conditional-if configured | | | | | #### PreLoad/Dynamic json Objects * "Preload\_Configuration" - for Pre-Load configuration parameters * "Dynamic\_Configuration" - for Dynamic configuration parameters #### VAS Wallet Read Configuration Parameters | json Key | Data Rule | Ancestor | Type | Value | Description | | -------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Get\_Config\_Version" | M | N/A | String (ASCII) | "1.0" | Current version of get configuration structure and format for "VWI" kernel | | "Pre\_Load" | M | N/A | String (ASCII) | "true" or "false" | | | "VWI\_Wallets" | M | N/A | json Array | wallet configuration json Object | Array of "VWI" configured wallets | | wallet configuration json Object | O | Entry in "VWI\_Wallets" Array | json Object | "Source" | wallet configuration json Object | | "Protocol\_Name" | | | | | | | "Protocol\_Version" | | | | | | | "Wallet\_App\_Version" | | | | | | | "APDU\_Max\_Len" | | | | | | | "Cmd\_Opts" | | | | | | | "Services" | | | | | | | "Merchant" | | | | | | | "AIDs" | | | | | | | "Service\_Type\_List" | | | | | | | "Push\_Data" | | | | | | | "AutoPay" | | | | | | | "terminal\_caps" | | | | | | | "Source" | M | wallet configuration json Object | String (ASCII) | Variable | Wallet source name | | "Protocol\_Name" | M | wallet configuration json Object | String (ASCII) | Variable | Wallet protocol name. Example: "VWI\_Kernel | | "Protocol\_Version" | M | wallet configuration json Object | String (ASCII) | Variable | Wallet protocol version. String of positive numbers | | "Wallet\_App\_Version" | M | wallet configuration json Object | Integer | Variable | | | "APDU\_Max\_Len" | M | wallet configuration json Object | Integer | Variable | Size of chunked APDU packer. Min- 1 byte, Max(default) - 255 bytes | | "Cmd\_Opts" | M | wallet configuration json Object | json Object | "Cmd\_Type" | Keeps an optional json object configuring command options | | "Auth\_Param" | | | | | | | "Encr\_Param" | | | | | | | "Cmd\_Type" | M | "Cmd\_Opts" | String (ASCII) | "Get" | Get VAS data from the smart device | | "Auth\_Param" | M | "Cmd\_Opts" | Boolean | 0-Disabled, 1-Enabled | Enable/disable authentication process | | "Encr\_Param" | M | "Cmd\_Opts" | Boolean | 0-Disabled, 1-Enabled | Enable/disable encryption/decryption process | | "Services" | M | wallet configuration json Object | json Array | Service json Object | Array for all configured services | | Service json Object | M | Entry in "Services" Array | json Object | "Service\_Type" | Information about configured services | | "Service\_Issuer\_Id" | | | | | | | "Service\_Issuer" | | | | | | | "Service\_Type" | M | Service json Object | String (ASCII) | [Service Types](broken://pages/e0ae9aa1ba926a905b0b4e8c0c1dc9c644a7637b#subsec_vwi_vas_kern_service_types) | Service type. Examples: "Coupon", "Loyalty" | | "Service\_Issuer\_Id" | C | Service json Object | String (number 0-4294967294) | Variable | Service issuer identifier. If configured, number between 0-4294967294 | | "Service\_Issuer" | C | Service json Object | String (ASCII) | [Service Issuer](broken://pages/e0ae9aa1ba926a905b0b4e8c0c1dc9c644a7637b#subsec_vwi_vas_kern_service_issuer) | Service issuer name. If configured | | "Merchant" | M | wallet configuration json Object | json Object | "Merchant\_Name" | Command/Authentication/Encryption options | | "Merchant\_Id" | | | | | | | "Merchant\_Store\_Code" | | | | | | | "Merchant\_Type" | | | | | | | "Terminal\_Id" | | | | | | | "Store\_Id" | | | | | | | "Merchant\_Generic\_Data" | | | | | | | "Merchant\_Phone" | | | | | | | "Merchant\_Name" | M | "Merchant" | String (ASCII) | Variable | Merchant name | | "Merchant\_Id" | M | "Merchant" | String (BCD) | Variable | Merchant ID. Must be 8-digit number | | "Merchant\_Store\_Code" | O | "Merchant" | String (ASCII) | Variable | Merchant Postal, Area, Store Code | | "Merchant\_Type" | O | "Merchant" | String (ASCII) | Variable | Merchant type/category | | "Terminal\_Id" | O | "Merchant" | String (ASCII) | Variable | Terminal ID | | "Store\_Id" | O | "Merchant" | String (ASCII) | Variable | Store ID | | "Merchant\_Generic\_Data" | O | "Merchant" | String (ASCII) | Variable | Merchant generic data | | "Merchant\_Phone" | O | "Merchant" | String (ASCII) | Variable | Merchant phone number | | "AIDs" | C | wallet configuration json Object | json Array | aid json Object | Array of application ID's for secondary select | | aid json Object | M | Entry in "AIDs" Array | json Object | "aid" | | | "aid" | M | aid json Object | String (ASCII) | Variable | AID value | | "Service\_Type\_List" | C | wallet configuration json Object | json Array | Service Type Object | List of service types | | Service Type Object | M | Entry in "Service\_Type\_List" Array | json Object | "Service\_Type" | | | "Service\_Type" | M | Service Type Object | String (ASCII) | [Service Types](broken://pages/e0ae9aa1ba926a905b0b4e8c0c1dc9c644a7637b#subsec_vwi_vas_kern_service_types) | Service type. Examples: "Coupon", "Loyalty" | | "Push\_Data" | C | wallet configuration json Object | json Object | "Customer\_Data" | Keeps an optional json objects to be pushed to the smart device. Conditional if it exists. | | "New\_Service\_List" | | | | | | | "Service\_Status\_List" | | | | | | | "Transaction\_Data" | | | | | | | "Customer\_Data" | C | "Push\_Data" | json Array | Customer Data Object | Objects to process customer data through appropriate function. May be used on "Push" or/and "Get" commands | | Customer Data Object | C | Entry in "Customer\_Data" Array | json Object | "Type" | | | "Value" | | | | | | | "Type" | C | Customer Data Object | String (ASCII) | Variable | Indicating type of function for customer data. Example: "DU" is a dynamic URL function | | "Value" | C | Customer Data Object | String (ASCII) | Variable | Actual customer data | | "New\_Service\_List" | C | "Push\_Data" | json Array | New Service Object | Array of new services | | New Service Object | C | Entry in "New\_Service\_List" array | json Object | "New\_Service\_Type" | | | "Service\_Issuer\_Id" | | | | | | | "Service\_Issuer" | | | | | | | "Service\_Title" | | | | | | | "Service\_URL" | | | | | | | "New\_Service\_Type" | M | New Service Object | String (ASCII) | Variable | [New Service Type](broken://pages/e0ae9aa1ba926a905b0b4e8c0c1dc9c644a7637b#subsec_vwi_vas_kern_new_service_type) | | "Service\_Issuer\_Id" | C | New Service Object | String (number 0-4294967294) | Variable | Service issuer identifier. Number between 0-4294967294 (must be integer in the system) | | "Service\_Issuer" | C | New Service Object | String (ASCII) | [Service Issuer](broken://pages/e0ae9aa1ba926a905b0b4e8c0c1dc9c644a7637b#subsec_vwi_vas_kern_service_issuer) | Service issuer name | | "Service\_Title" | M | New Service Object | String (ASCII) | Variable | Title of the service | | "Service\_URL" | M | New Service Object | String (ASCII) | Variable | Service URL | | "Service\_Status\_List" | C | "Push\_Data" | json Array | Service Status Object | Array of services status objects per service | | Service Status Object | C | Entry in "Service\_Status\_List" array | json Object | "Service\_Object\_Id" | Array of services status objects per service. | | "Usage\_Status" | | | | | | | "Usage\_Title" | | | | | | | "Usage\_Description" | | | | | | | "Update\_Operation" | | | | | | | "Update\_Payload" | | | | | | | "Usage\_Status" | C | Service Status Object | String (ASCII) | Variable | [Usage Status](broken://pages/e0ae9aa1ba926a905b0b4e8c0c1dc9c644a7637b#subsec_vwi_vas_kern_usage_status) | | "Usage\_Title" | C | Service Status Object | String (ASCII) | Variable | Title of usage action | | "Usage\_Description" | C | Service Status Object | String (ASCII) | Variable | Description of usage action | | "Update\_Operation" | C | Service Status Object | String (ASCII) | Variable | [Update Operation](broken://pages/e0ae9aa1ba926a905b0b4e8c0c1dc9c644a7637b#subsec_vwi_vas_kern_update_operation) | | "Update\_Payload" | C | Service Status Object | Integer | Variable | Update action payload | | "Service\_Object\_Id" | M | Service Status Object | String (hex) | Variable | Service object ID | | "Transaction\_Data" | O | "Push\_Data" | json Object | "Date\_Time" | type: String (ASCII). Conditional-if configured | | "Merchant\_Name" | type: String (ASCII). Conditional-if configured | | | | | | "Merchant\_Info" | type: String (ASCII). Conditional-if configured | | | | | | "Terminal\_Id" | type: String (ASCII). Conditional-if configured | | | | | | "Store\_Id" | type: String (ASCII). Conditional-if configured | | | | | | "Acquirer\_Id" | type: String (ASCII). Conditional-if configured | | | | | | "Trans\_Id" | type: String (ASCII). Conditional-if configured | | | | | | "Trans\_Status" | type: String (ASCII). Conditional-if configured | | | | | | "Trans\_Type" | type: String (ASCII). Conditional-if configured | | | | | | "Amount\_Pre\_Discount" | type: Number. Integer only, no floating point permitted. Conditional-if configured. | | | | | | "Final\_Amount" | type: Number. Integer only, no floating point permitted. Conditional-if configured. | | | | | | "Trans\_Currency\_Code" | type: String (ASCII). Conditional-if configured | | | | | | "Trans\_Currency\_Exp" | type: String (ASCII). Conditional-if configured | | | | | | "Type\_Of\_Goods" | type: String (ASCII). Conditional-if configured | | | | | | "AutoPay" | O | wallet configuration json Object | Boolean | Variable | In case of "Payment\&VAS", "Payment\|VAS", "Payment" and an error occurs on VAS side, terminal goes to payment if and only if AutoPay is enabled. 0-Disabled, 1-Enabled | | "Capabilities" | O | wallet configuration json Object | String | "Payment\&VAS" | Terminal capable to perform both VAS and Payment transactions. Used as default | | "Payment\|VAS" | Terminal capable to perform both Payment transactions if no VAS data received | | | | | | "Payment" | Terminal capable to perform Payment transactions only | | | | | | "VAS" | Terminal capable to perform both VAS transactions only | | | | | #### VAS Wallet Response Format | json Key | Data Rule | Ancestor | Type | Value | Description | | ---------------------- | ------------- | ---------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | "Source" | C | N/A | String (ASCII) | Variable | Wallet application name. Examples: "AndroidPay". | | "Format\_Version" | C | N/A | String (ASCII) | 1.0 | Version of response format | | "Mobile\_App\_Version" | C | N/A | String (ASCII) | Variable | Version of mobile wallet application | | "Min\_App\_Version" | C | N/A | String (ASCII) | Variable | Minimum application version (Mobile side) | | "Max\_App\_Version" | C | N/A | String (ASCII) | Variable | Maximum application version (Mobile side) | | "Merchant\_Name" | O | N/A | String (ASCII) | Variable | Merchant Name. Examples: "ABC Store" | | "Merchant\_Id" | O | N/A | String (BCD) | Variable | Merchant Identifier. Must be 8-digit number | | "Services\_List" | O | N/A | json Object | "Service\_Issuer" "Service\_Issuer\_Id" "Services" | Keeps an optional json object that represents customer information | | "Service\_Issuer" | M | "Services\_List" | String (ASCII) | Variable | [Service Issuer](broken://pages/e0ae9aa1ba926a905b0b4e8c0c1dc9c644a7637b#subsec_vwi_vas_kern_service_issuer) | | "Service\_Issuer\_Id" | M | "Services\_List" | String (number 0-4294967294) | Variable | Service issuer identifier. Number between 0 -4294967294 (must be integer in the system) | | "Services" | M | "Services\_List" | json Object | "Service\_Type" "Service\_Object\_Id" "Service\_Number" "Expiration" "CCV1" "Track1" "Track2" "PIN" "Customer" | Array of services | | "Service\_Type" | M | "Services" | String (ASCII) | Variable | [Service Types](broken://pages/e0ae9aa1ba926a905b0b4e8c0c1dc9c644a7637b#subsec_vwi_vas_kern_service_types) | | "Service\_Object\_Id" | C | "Services" | String (hex) | Variable | Service object identifier | | "Service\_Number" | C | "Services" | String (BCD) | Variable | Service number | | "Expiration" | C | "Services" | String (BCD) | Variable | Expiration date | | "CCV1" | C | "Services" | String (BCD) | Variable | CVV1 | | "Track1" | C | "Services" | String (ASCII) | Variable | Track 1 data | | "Track2" | C | "Services" | String (ASCII) | Variable | Track 2 data | | "PIN" | C | "Services" | String (BCD) | Variable | PIN | | "Customer" | C | "Services" | json Object | "Customer\_ID" "Wallet\_Issuer" "Customer\_Name" "Tap\_Id" "Mobile\_Device\_Id" "Customer\_Email" "Preferred\_Language" | Keeps an optional json object represents customer information | | "Customer\_ID" | C | Customer | String (BCD) | Variable | Customer identifier | | "Wallet\_Issuer" | C | Customer | String (ASCII) | Variable | Wallet issuer | | "Customer\_Name" | C | Customer | String (ASCII) | Variable | Customer name | | "Tap\_Id" | C | Customer | String (BCD) | Variable | Tap identifier | | "Mobile\_Device\_Id" | C | Customer | String (BCD) | Variable | Mobile device identifier | | "Customer\_Email" | C | Customer | String (ASCII) | Variable | Customer Email | | "Preferred\_Language" | C | Customer | String (ASCII) | Variable | Preferred Language | | "Error" | O | N/A | String (ASCII) | "APDU\_SW" | APDU SW1 SW2 values | | Integer | "Code" | | | | | | String (ASCII) | "Description" | | | | | Appendix A - Sample Files ### Apple CXPI json File { "VAS\_Configuration" : { "Configuration\_version" : "1.0", "Targets" : \[ { "Source" : "ApplePay", "Wallet\_Config\_version" : "1.0", "Protocol\_Name" : "applepay\_vas", "Protocol\_Version" : "0100", "CustomPollData" : "80 10 81 10 60 10 08 08 05 6A 01 00 00 01", "Services" : \[ { "Service\_Type" : "BetaCoupon", "Service\_ID" : "pass.com.apple.wallet.vas.prodtest", "Service\_Issuer" : "Apple", "URL" : "[www.appleprodtest.com](http://www.appleprodtest.com)", "Vas\_Filter" : "01 00 00 00 00" }, { "Service\_Type" : "EncryptedCoupon", "Service\_ID" : "pass.com.verifone.test.B", "Service\_Issuer" : "Apple", "URL" : "[www.merchant3.com](http://www.merchant3.com)", "Vas\_Filter" : "01 00 00 00 00" } ], "Cmd\_Opts" : { "Cmd\_Type" : "Get", "Auth\_Param" : 0, "Encr\_Param" : 0 }, "Merchant" : { "Merchant\_Name" : "VerifoneQA", "Merchant\_ID" : "Jenny8675309" } }, ### Google CXPI json File { "Source" : "AndroidPay", "Wallet\_Config\_version" : "1.0", "Protocol\_Name" : "VWI\_Kernel", "Protocol\_Version" : "0001", "Wallet\_App\_Version" : 0, "APDU\_Max\_Len" : 255, "Services" : \[ { "Service\_Type" : "PLC" }, { "Service\_Type" : "Loyalty" }, { "Service\_Type" : "Coupon" }, { "Service\_Type" : "Gift Card" }, { "Service\_Type" : "Wallet Customer" } ], "Cmd\_Opts" : { "Cmd\_Type" : "Get", "Auth\_Param" : 1, "Encr\_Param" : 1 }, "Merchant" : { "Merchant\_Name" : "Merchant\_Name-1", "Merchant\_ID" : "88888888", "Merchant\_Type" : "Merchant\_Type-1", "Terminal\_Id" : "A01234C1", "Store\_Id" : "A01234D1" }, "AIDs" : \[ { "aid" : "a000000476d0000111" } ### Terminal json File In the sample file below, you can see that the "Capabilities" element defaults to VAS. The other options would be "Payment", "Payment\&VAS", or "Payment|VAS". | { | | -------------------------------- | | "Terminal\_Configuration": | | { | | "Configuration\_version": "1.0", | | | | "Terminal": | | { | | "PollTech": "ABF", | | "PollTime": 10000, | | | | "Terminal\_Capabilities": | | { | | "Capabilities" : "VAS", | | "Presigned\_Auth" : 0, | | "AutoPay" : 0, | | | | "system": | | { | | "Standalone" : 1, | | "Semi\_integrated" : 0, | | "Unattended" : 0, | | "Online" : 1, | | "Offline" : 0, | | "MMP" : 0, | | "Compression": 1 | | }, | | | | "UI": | | { | | "Printer" : 1, | | "Printer\_Graphics" : 1, | | "Display" : 0, | | "Images" : 1, | | "Audio" : 0, | | "Animation" : 1, | | "Video" : 1 | | }, | | | | "CVM": | | { | | "Online\_PIN" : 1, | | "CD\_PIN" : 0, | | "Signature" : 1, | | "No\_CVM" : 1, | | "Device\_Generated\_Code" : 0, | | "SP\_Generated\_Code" : 1, | | "ID\_Capture" : 1, | | "Biometric" : 0 | | }, | | | | "Check\_Out": | | { | | "Digital\_Receipt" : 1, | | "Service\_Issuance" : 0, | | "OTA\_POS\_Data" : 1 | | } | | } | | }, | | "Log": | | { | | "Log\_Level\_Bit\_Map":1 | | } | | } | | } | ### APPLE.wky File { "wallet\_type\_list": { "apple\_pay\_vas": \[ { "merchant\_id\_list": \[ { "key\_list": \[ { "action": "add", "key\_type": "ECC", "key\_id": "fe65014e", "key\_service\_type": "Decryption", "encryption\_kek\_id": "54B636", "encryption\_iv": "72FB139B6AD0C60E", "encrypted\_key": "arb8JCI0gygFS78IkKVY0w7jvfSTEgFTsG2xbk8KnXt1YmTd9SYM3q4ZdOHmh8zMnZrngWZzdzy/w/6Vdlvq/7chA+WhQDREegfkcLMKakwAIdnHAtw3uECa5lMVchFJ5/gLW13njPgerL4gc2lBSQ9RPic7nnyive6+8Xk13MkEn5T/fZqtVBTryclDTje3aTb0HonEChlhLfBD+1w7A/c1ZpQ9RYRzNcLW9R2sqbNJnPTdNB21nriXdcg4iJF169w23Gs2WoZ+vgQzBJTIDIOGvEhI8CrXAbP8Q5zSwW4atX3cwR67PLi9c8fDk508AZPd255GRWfqybYn+UlAShsmxhI+MV+/", "MAC": "C06DDAFF25E954BB", "timestamp": "2017-07-11T13:34:40.088Z" } ], "merchant\_id": "pass.com.verifone.test.B" } ], "merchant\_name": "Alpha" } ] } } ### GOOGLE.wky File { "wallet\_type\_list": { "vwi": \[ { "wallet\_name":"AndroidPay", "merchant\_id\_list": \[ { "merchant\_name": "Verifone\_SQA" , "merchant\_id":"12345678", "key\_list": \[ { "action":"add", "key\_version":"9903dd05", "key\_type":"ECC", "key\_service\_type":"Signing", "kbpk\_id":"82E71F", "encryption\_iv":"915A77A93A117AD0", "encrypted\_key":"cQovEGfPemHcvFag8J9yt1aBptKNqG1CE52tssFLUQrKTN68nV/W+VzvjFlx6OTtc2/6NFwhfiL+A8tkaXjJokIhMDwLe3lUjOtWE26NJvETVfxFEUEwhuCdo4Xm0yGzMOHXs1NyYr9Hmiep/PZz4svzrnD74ZMZYILfMBGzweEaqyczN9rjkJ+n/mwXmQ70nMU7t2ggzghJQzeVJ7JnXDk9V45dn9b32Sx30/WmQJ55/+EKmcjCAOE3mWrs3lkTgmzdhCHO+ONTtq3fL9BykWw7ow2QqVOFWoEjltsALifY3EgFjnQu4XKSSVZlGHbLp6KlqaAqS7pl1WBrSKYtRleUlK8rBPzwka29g7OiraqRwofmqqJYwNLVP/FTJ8+0PYfHz4W4sI4xgfJlk3Rtcg==", "MAC":"9D152189175B9EE2", "timestamp":"2017-09-12T14:24:00Z" } ] } ] } ] } } Appendix B - Key Order Forms ### Apple Keys Your Verifone representative will supply the Merchant Name and the Service ID (provided by the merchant). | **Merchant URL (pass type identifier)** | **Associated Key** | | --------------------------------------- | ------------------ | | “abcstore.pass.coupon” | key 1 | | “abcstore.pass.coupon2” | key 1, key 3 | | “abcstore.pass.loyalty” | key 2 | | “abcstore.pass.loyalty2” | key 1, key 2 | ### Google Keys Initially, the merchant will need to request a public key from Verifone to add to their rewards card. Merchants should reach out to their Verifone sales engineer or account manager and provide their merchant name and request a Google collector ID. Verifone will acquire a public key for the merchant and send the information to the merchant via email. This process will take a few days. | **Verifone Wallet Key Generation Request** | | ---------------------------------------------------------------------------------------------- | | **Date:** | | **Email:** | | **Create KBPK:** | | **Wallet\_Name**\*\* | |

VSS Script/Slot #
(For Verifone Use Only)

| | **Merchant Information** | | **Merchant Name** | | | | | | | | | | Add lines as necessary | ***\*A unique 4-byte hex value specific to the merchant - given by the Wallet provider.*** **\_** A unique wallet label as defined by the wallet provider. This name is the wallet label return as part of the Wallet response to ‘Select OSE request’.\_\*\* **\_**\* 3 bytes hex value to identify KBPK key. If not provided a new one will be generated, if provided it will be reused. KBPK id can be found inside the *.wky file provided after previous key requests.\_*\* **\_**\*\* Date (format YYMMDD) and a .wky extension will be added to file name. If not provided, the first merchant name in the list will be used. Example for merchant name ‘shop’: ‘shop\_180405.wky’\_\*\* **By signing below, I am attesting that I am a Verifone Requestor who has been authorized and pre-approved to make the Google Wallet Merchant Key(s) request above.** | **Signature** | | | | | | | | **Date** | | | ---------------- | - | - | - | - | - | - | - | --------- | - | | **Printed name** | | | | | | | | **Title** | | --- # 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-mobile-wallet-setup-guide-2.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.