# XPI Mobile Wallet Setup Guide 1\_4 ![new verifone](/files/d1b89aa81cb166183d4ba1515932a12d31b5180c)­ **Setup Guide** **XPI Mobile Wallet VAS** Document Version: 1.4 Release Date: 08/02/18 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 | | -------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | | | | | 1.4 | 08/02/18 | CatherineP1 | Updated Appendix B, Google Key form; changed Apple & Google Script ID from 63 to 61; replaced references of Apple Pay to Apple VAS 2.0 and references of Google Pay to Google Smart Tap 2.1; replaced references of Android Pay to Google Smart Tap 2.1 | | 1.3 | 07/03/18 | CatherineP1 | Changed references of GooglePay/Google Pay to AndroidPay/Android Pay | | 1.2 | 06/13/18 | CatherineP1 | Replaced WKY with wky & JSON w/ json in text & illustrations, except within commands; added more info about updating timezone & date/time for Apple wallet keys | | 1.1 | 05/1/18 | CatherineP1 | Minor changes from additional technical review, including updating the C30 & F30 response codes | | 1.0 | 05/15/18 | CatherineP1 | Initial release | Table of Contents [Chapter 1 – Introduction 1](#_Toc12281068) [Document Overview 1](#_Toc12281069) [Using This Document 1](#_Toc12281070) [Terms 2](#_Toc12281071) [Data Types & Rules 3](#_Toc12281072) [Data Types 3](#_Toc12281073) [Chapter 2 – Overview 4](#_Toc12281074) [Introduction 4](#_Toc12281075) [Mobile Wallet VAS Features 5](#_Toc12281076) [One-Tap 5](#_Toc12281077) [Two-Tap 5](#_Toc12281078) [Auto-Presentment 5](#_Toc12281079) [Mobile Wallet Auto-Enrollment 5](#_Toc12281080) [Card and Payment Types 5](#_Toc12281081) [Primary Components 6](#_Toc12281082) [Encryption Keys 6](#_Toc12281083) [VSS Script ID & Slot 6](#_Toc12281084) [VSS Script for Wallet Keys 6](#_Toc12281085) [Wallet Key json File (\*.wky) 7](#_Toc12281086) [Terminal json File 7](#_Toc12281087) [CXPI json File 7](#_Toc12281088) [Prerequisites 8](#_Toc12281089) [VAS Transaction Overview 8](#_Toc12281090) [Software 8](#_Toc12281091) [Software Components for Engage Devices 8](#_Toc12281092) [Software Descriptions 9](#_Toc12281093) [Hardware 10](#_Toc12281094) [Terminal Capability Options 12](#_Toc12281095) [VAS or Payment 12](#_Toc12281096) [VAS & Payment 12](#_Toc12281097) [VAS Only 12](#_Toc12281098) [Payment Only 12](#_Toc12281099) [Integration 12](#_Toc12281100) [Chapter 3 - Processing XPI Commands 13](#_Toc12281101) [XPI Platform Components 13](#_Toc12281102) [Mobile Wallet Transactions 13](#_Toc12281103) [F30 EMV Chip Command 14](#_Toc12281104) [F30 Request Format 14](#_Toc12281105) [F30 Request Data Elements 14](#_Toc12281106) [F30 Response Format 15](#_Toc12281107) [F30 Response Data Elements 15](#_Toc12281108) [C30 Enable Card Insertion 17](#_Toc12281109) [C30 Request Format 17](#_Toc12281110) [C30 Request Data Elements 17](#_Toc12281111) [C30 Parameter List 18](#_Toc12281112) [C30 Response Format 19](#_Toc12281113) [C30 Response Data Elements 19](#_Toc12281114) [D41 VAS Only Transaction 19](#_Toc12281115) [D41 Request Format 19](#_Toc12281116) [D41 Request Data Elements 20](#_Toc12281117) [D41 Response Format 20](#_Toc12281118) [D41 Response Data Elements 20](#_Toc12281119) [D41 Response Example 20](#_Toc12281120) [D41 Additional Information: 21](#_Toc12281121) [D28 Retrieve Non-Payment Wallet Information Separately Transaction 21](#_Toc12281122) [D28 Request Format 21](#_Toc12281123) [D28 Request Data Elements 21](#_Toc12281124) [D28 Response Format 21](#_Toc12281125) [D28 Response Data Elements 21](#_Toc12281126) [D28 Response Example 22](#_Toc12281127) [S20 Obtain Card Data Transaction (Swipe or Tap) 22](#_Toc12281128) [S20 Request Format 22](#_Toc12281129) [S20 Request Data Elements 22](#_Toc12281130) [S20 Response Format 23](#_Toc12281131) [S20 Response Data Elements 23](#_Toc12281132) [S20 Additional Information: 23](#_Toc12281133) [D50 Upload/Download Configuration File 24](#_Toc12281134) [D50 Request Format 24](#_Toc12281135) [D50 Request Data Elements 24](#_Toc12281136) [D50 Response Format 25](#_Toc12281137) [D50 Response Data Elements 25](#_Toc12281138) [Chapter 4 – Apple VAS 2.0 27](#_Toc12281139) [Product Name References 27](#_Toc12281140) [Rewards Provisioning 27](#_Toc12281141) [CXPI json File for Apple VAS 2.0 28](#_Toc12281142) [Sample C30 Wallet Command 29](#_Toc12281143) [Requesting Public, Private & Wallet Keys 30](#_Toc12281144) [Apple VAS Decryption 31](#_Toc12281145) [Apple VAS Kernel Interface 32](#_Toc12281146) [Architecture 32](#_Toc12281147) [SW1 & SW2 33](#_Toc12281148) [VAS Wallet Configuration Parameters 34](#_Toc12281149) [Read VAS Wallet Configuration Parameters 35](#_Toc12281150) [VAS Wallet Dynamic Configuration Parameters 37](#_Toc12281151) [VAS Wallet PreLoad Configuration Parameters 38](#_Toc12281152) [VAS Wallet Response Format 39](#_Toc12281153) [Chapter 5 – Google Smart Tap 2.1 40](#_Toc12281154) [Product Name References 40](#_Toc12281155) [Invoking Google json Preload 40](#_Toc12281156) [9F4E Geo Location 41](#_Toc12281157) [Loyalty Bounce-Back 42](#_Toc12281158) [Google Smart Tap 2.1 VAS Configuration 42](#_Toc12281159) [Sample Wallet Command 42](#_Toc12281160) [Google Decryption/Key Management 43](#_Toc12281161) [Requesting Public, Private & Wallet Keys 43](#_Toc12281162) [VWI VAS Kernel Interface 44](#_Toc12281163) [Architecture 45](#_Toc12281164) [SW 1 & SW2 45](#_Toc12281165) [Types 46](#_Toc12281166) [Service Types 46](#_Toc12281167) [Service Issuer 46](#_Toc12281168) [Expected Format 46](#_Toc12281169) [New Service Type 46](#_Toc12281170) [Usage Status 47](#_Toc12281171) [Update Operation 47](#_Toc12281172) [VWI VAS APDU Message Format 47](#_Toc12281173) [VWI VAS APDU - P2 Extension 48](#_Toc12281174) [VAS Wallet PreLoad/Dynamic Configuration Parameters 50](#_Toc12281175) [PreLoad/Dynamic json Objects 52](#_Toc12281176) [VAS Wallet Read Configuration Parameters 53](#_Toc12281177) [VAS Wallet Response Format 57](#_Toc12281178) [Appendix A – Sample Files 59](#_Toc12281179) [Apple CXPI json File 59](#_Toc12281180) [Google CXPI json File 60](#_Toc12281181) [Terminal json File 61](#_Toc12281182) [APPLE.wky File 62](#_Toc12281183) [GOOGLE.wky File 63](#_Toc12281184) [Appendix B – Calculating C30 with Tags & Lengths 64](#_Toc12281185) [Original Wallet C30 Command 64](#_Toc12281186) [Instructions 64](#_Toc12281187) [Length Change Step 1 65](#_Toc12281188) [Length Change Step 2 65](#_Toc12281189) [Updated Wallet C30 Command 65](#_Toc12281190) [Appendix C – Key Order Forms 67](#_Toc12281191) [Apple Keys 67](#_Toc12281192) [Google Keys 68](#_Toc12281193) Chapter 1 – Introduction ### Document Overview 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. | | -- | ------- | --------------------------------------------------------------------------------------------------------------------- | | | IMPORTANT | | | - | --------- | - | #### 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 | | FP | Forms processor | | 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 | 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. #### 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 | Chapter 2 – Overview ### Introduction 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/cf89d053a081550f268ba2ea6f869c07edf5e48b) 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. Customers may have multiple VAS cards loaded in their mobile wallets for different merchants. #### 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. The wallet key provider will provide mobile pass/service wallet keys in the appropriate format to Verifone Key Services once they are generated. Verifone Key Services will install the 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 in config.usr1 (/home/user1/flash) on Mx devices. 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,* *Terminal json* File. #### 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 supports 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. | | -- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 🛈 | NOTE | CAMCORE.INI must be signed and authenticated. | | -- | ---- | --------------------------------------------- | ### VAS Transaction Overview The VAS transaction consists of the following four major steps: 1. Technology Selection –occurs when the payment application enables the card read (RF Polling) 2. Wallet Selection – occurs when the smart device is presented and authenticated 3. Data Exchange – data is exchanged between the smart device and the payment terminal 4. 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 | | XPI Version | 19.01.11.xx | | 🛈 | NOTE | Currently, the Forms Processor application has not been released for support with the XPI 19.01.11.xx application version; however, it will be supported on the M400 and MX 9xx devices only in a future release. | | -- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | #### 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. * Verifone External PIN Pad Interface (XPI) Verifone XPI is an application that runs on Verifone’s PIN Pads and mobile devices. The application allows integrators to send commands to allow for card processing and security functions. XPI has a defined set of commands that are supported for handling payment- and encryption-related functions, such as requesting card and encrypted card data information. * Forms Processor Verifone Forms Processor is the application that works in parallel with XPI to allow integrators and merchants to customize the forms displayed on the device. Forms Processor does not include functionality to process payment- or encryption-related commands. Instead, Forms Processor focuses only on the screen display. . | 🛈 | NOTE | Please note that the Forms Processor is ONLY for the M400 and MX series terminals; other Engage devices do not require the Forms Processor | | -- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------ | ### Hardware You can set up and use XPI 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). | | - | --------- | -------------------------------------------------------------------------------------------- | Following devices are supported for XPI Mobile Wallet VAS. | Supported Engage Devices | | --------------------------------------------------------------------------------------------------- | | **e285**![](/files/daa8ebc82313b7a0f15528fc0bdb9df0f96617c1) | | **P200**![p200\_front\_engage](/files/08fb2d71b29b260a5a49685cc2c63522bb0aa03c) | | **V200c**![v200c\_front\_screen\_3118 × 4536](/files/296e686b6bd692b522f84724300cf723015817b0) | | **V240m**![](/files/814db0131b932619437c9dce9fd39177156de07f) | Figure 2 Engage Devices | Supported UX Series Devices | | ------------------------------------------------------------------------ | | **UX** **100**![UX 100](/files/6808f321c2c1b7eb7ed485d427b250781b12e954) | | **UX** **301**![](/files/26a52b6217e694ff1afabc958058134a1d640387) | Figure 3 UX Series Devices ### 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,* *Terminal json* File 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 XPI 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. Chapter 3 - Processing XPI Commands ### XPI Platform Components As Figure 4 illustrates, the Engage solution uses common, re-usable building blocks deployed as one application. ![](/files/a3820a9d98fa36062b974ad78fd19f7bcc7d28d2) Figure 4 Engage Application Topology ### Mobile Wallet Transactions This document includes details for the following transactions: * F30 – Enable EMV QuickChip * C30 – Enable card insertion * D41 – VAS-only transaction * D28 – Retrieve VAS data (non-payment data) separately * S20 – Obtain card data transaction * D50 – Upload & download configuration file | 🛈 | NOTE | When using the C30 and/or F30 commands with wallet enabled, you must ensure you set the VAS mode to Payment in the preload. | | -- | ---- | --------------------------------------------------------------------------------------------------------------------------- | ### F30 EMV Chip Command The F30 command is an EMV Chip command for XPI that can be used for QuickChip and non-QuickChip transactions. This command combines the traditional C30, C32, C34, C36, I02, E07 commands. #### F30 Request Format F30<\> #### F30 Request Data Elements | Element | Description | Field Type | Field Length | Additional Information | | -------- | ----------------------------------- | ------------ | ------------ | ---------------------- | | | Start of text | Hexadecimal | 1 | | | F30 | Packet identifier/command | Alphanumeric | 3 | | | \ | Tag 1 | Hexadecimal | Variable | | | \ | Tag 2 | Hexadecimal | Variable | | | | Tag *n* | Hexadecimal | Variable | | | | End of text | Hexadecimal | 1 | | | | Longitudinal Redundancy Check digit | Hexadecimal | 1 | | #### F30 Response Format F30\> #### F30 Response Data Elements | Element | Description | Field Type | Field Length | Additional Information | | -------- | -------------------------------- | ------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Start of text | Hexadecimal | 1 | | | F30 | Packet identifier/command | Alphanumeric | 3 | | | | F30 command response | Alphanumeric | 2 |

00 - success 01 - invalid command code/data format 02 - N/A: Timeout 03 - cancelled 04 - N/A: Non-ISO Card (MSR/MSD CTLS) 05 - chip error 06 - card removed 07 - N/A: candidate list empty 08 - card blocked 09 - CTLS error with extra codes
(ex: C3131 Mx) 10 - previous step missing 11 - response has more packets 51 - VAS and Payment; both happen 52 - VAS or payment; VAS happens 56 – VAS fail 70 - N/A: WIC Card inserted 79 - For EMV contact transaction when
PIN is entered and there is no
DUKPT keys in the terminal 88 – More data expected, response is
split into multiple data packets 91 - issuer authentication failed, or card is
in an error state (EMV Status Code =
0x6985) 99 - failure/busy

| | \ | Tag 2 | Hexadecimal | Variable | | | | Tag *n* | Hexadecimal | Variable | | | | End of text | Hexadecimal | 1 | | | | Longitudinal Redundancy response | Hexadecimal | 1 | -- OK -- LRC Incorrect | **Request Format Tags** **Optional Tags** | Tag Name | Description | | -------- | ------------------------------------------------------------------------------------------- | | <9F><30> | Timeout: Default value is infinite timeout for EMV Contact and 256 seconds if EMV CTLS used | **Custom Tags** | Tag Name | Description | | -------- | ----------------------- | | <9F><0C> | Wallet input parameters | **Response Format Tags** **Default EMV Tags Returned** | Tag Name | Description | | -------- | ------------------------------------- | | <4F> | AID | | <9F><12> | Application Preferred Name | | <50> | Application Label | | <5F><30> | Service Code | | <5F><20> | Cardholder Name | | <57> | Track 2 | | <5A> | PAN | | <5F><24> | Expiry Date | | <9F><33> | Terminal Capabilities | | <5F><34> | PAN Sequence Number | | <5F><25> | Application Effective Date | | <5F><28> | Issuer Country Code | | <5F><2D> | Language Preference | | <9F><39> | POS Entry Mode (Mandatorily returned) | | <95> | TVR | | <9B> | TSI | | <9F><27> | CID | | <8A> | Auth Response Code | | <9F><26> | Application Cryptogram | | <9F><36> | ATC | **Custom Tags** | Tag Name | Description | | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | <9F><0A> |

If wallet support is on, and smart device is tapped with wallet loyalty/coupons:

  • 3-byte More indicator tag
  • <9FA00ALen> BERTLV length in hex for the More indicator
    ‘Y’ or ‘N’ - 0x59 or 0x4E

NOTE:

  • If the value is ‘Y’, it means that there are succeeding F30 responses
| | <9F><10> |

If wallet support is on, and smart device is tapped with wallet loyalty/coupons:

  • Tag containing json object
  • <9FA010Len>BERTLV Tag Length – length containing whole json object dump
    <9FA010 data> Compressed json object dump with stripped spaces/line feeds
| | <9F><11> |

If wallet support is on and smart device is tapped with wallet loyalty/coupons:

  • Tag to show type of wallet tap "APY" or "GOG"
  • <9FA011Len>BERTLV Tag Length for the type of wallet tap
  • <9F><11> Tag containing "APY" or "GOG"
| | <9F><34 | Verifone custom Eparm encryption tag: Length: H Value: Verifone Custom tag for Eparms data (if available) (from E02 response) Example: <9F><34> <2E>01010026250260350200150b325-040-25418012380206 | | <9F><35> | Verifone custom Eparm Result tag (VSP eparms only) Length 1H Value Response code from ex E02 response in hex | | <9F><3A> | Verifone custom Encryption Result tag (non VSP encryptions) Length 1H Value Response code from ex E07 response in hex | | 🛈 | NOTE | The F30 command behaves exactly like the C30 for EMV CTLS. The extra input tags provided from the C32, C34, and I02 traditional commands in the F30 makes no difference to an EMV CTLS tap. The tags are ignored by XPI for an EMV CTLS tap | | -- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ### C30 Enable Card Insertion The C30 command is used to prompt for card insertion. | | IMPORTANT | Verifone strongly recommends you use the F30 instead of the S20, particularly since the EMV migration is currently taking place. Also, F30 without amount can be used, if XPI is configured for MSD. S20 should only be used by customers who have no intention of moving to EMV payments in general at the same time as making Wallet changes, and who intend to use XPI for MSD transactions. | | - | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | #### C30 Request Format C30 #### C30 Request Data Elements | Element | Description | Field Type | Field Length | Additional Information | | ------- | ----------------------------------------- | ------------ | ------------ | ---------------------- | | | Start of text | Hexadecimal | 1 | | | C30 | Packet identifier/command | Alphanumeric | 3 | | | | Size of parameters list in 2 binary bytes | Hexadecimal | 2 | | | | List of parameters in TLV format | Hexadecimal | Variable | | | | End of text | Hexadecimal | 1 | | | | Longitudinal Redundancy Check digit | Hexadecimal | 1 | | #### C30 Parameter List | Parameter | Description | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | C1 | C1x01x78; Len = 1, timeout=120 secs | | C1 | C1x04x00001234; Len = 4, Transaction Sequence Counter in BCD format | | C1 | C1x03x06x02x03; Len = 3, Date = 99/99/99 | | C1 | C1x03x06x15x00; Len = 3, Time = 99:99:99 | | C1 | C1x01x00; Len = 1, txn type = 0, typically set to 0x00 for goods and services | | C1 | C1x01x31; Len = 1, Language = ‘1’ (English) Language = ‘2’ (French) The language codes in this command are different than any other command, because the kernel uses ‘1’ and ‘2’ language codes instead of ‘0’ and ‘1’ | | C1 | C1x00; Len = 0, No Curr Code | | C1 | C1x01x01; Len = 1, Amt = 0.01 C1x04x3Bx9AxC9xFF; Len = 4, Amt = 9,999,999.99 (Max amount) Values should be sent in Hexadecimal format. Required for all transactions | | C1 | C1x01x00; Len = 1, Amount Other = 0.00 Values should be sent in Hexadecimal format. Required for all transactions.**NOTE:** For refund transactions, Amount Other value must be set to 0.00 (Amount Other = 0.00) | | C1 | C1x01x20; Len = 1, Contactless Transaction Type 00 (or empty) = Enable CTLS FF or 80 = Disable CTLS | | [9FA00C](#D41ApplePay) | Optional, if Wallet SmartTap for Google Smart Tap 2.1 is enabled. D41 components as defined in D41 command | #### C30 Response Format C30 #### C30 Response Data Elements | Element | Description | Field Type | Field Length | Additional Information | | ------- | -------------------------------- | ------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Start of text | Hexadecimal | 1 | | | C30 | Packet identifier/command | Alphanumeric | 3 | 0 = failure | | | Response code | Alphanumeric | 2 |

00 - success 01 - invalid command code/data format 02 - N/A: Timeout 03 - cancelled 04 - N/A: Non-ISO Card (MSR/MSD
CTLS) 05 - chip error 06 - card removed 07 - N/A: candidate list empty 08 - card blocked 09 - CTLS error with extra codes
(ex: C3131 Mx) 10 - previous step missing 11 - response has more packets 51 - VAS and Payment; both happen 52 - VAS or payment; VAS happens 56 – VAS fail 70 - N/A: WIC Card inserted 79 - For EMV contact transaction when
PIN is entered and there is no
DUKPT keys in the terminal 88 – More data expected, response is
split into multiple data packets 91 - issuer authentication failed, or card is
in an error state (EMV Status Code =
0x6985) 99 - failure/busy

| | | Response length | Hexadecimal | 2 | Size of parameters list in 2 binary bytes | | | Response list | Hexadecimal | variable | List of parameters in TLV format | | | End of text | Hexadecimal | 1 | | | | Longitudinal Redundancy response | Hexadecimal | 1 | -- OK -- LRC Incorrect | For detailed information on the C32, C34, and C36 transactions, please refer to the *External PINPad Interface* guide. ### D41 VAS Only Transaction The D41 command is used to get wallet-only data from a tap of a smart device. There is no payment data requested with this command. #### D41 Request Format D41JSON FORMATTED DYNAMIC VAS DATA REQUEST PARAMETERS Refer to *Appendix A, Sample Files* for more information. #### D41 Request Data Elements | Element | Description | Field Type | Field Length | Additional Information | | ----------------------------------------------------------- | ----------------------------------- | ----------- | ------------ | ---------------------- | | | Start of text | Hexadecimal | 1 | | | D41 | Packet identifier/command | Hexadecimal | 3 | | | | Field separator | Hexadecimal | 1 | | | | End of text | Hexadecimal | 1 | | | | Longitudinal Redundancy Check digit | Hexadecimal | 1 | | | **NOTE:** Valid if D41 succeeded and APPEND\_WALLETDATA = 1 | | | | | #### D41 Response Format D41RetVal<2byte length in hex><3 byte Wallet indicator>{RetValString}] #### D41 Response Data Elements | Element | Description | Field Type | Field Length | Additional Information | | ----------------------------------------------------------- | -------------------------------------- | ----------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Start of text | Hexadecimal | 1 | | | D41RetVal | D41 returned value | Numeric | 2 | 0 = failure 00 = success 01 = invalid command 02 = wallet not configured 03 = tech discovery failed 04 = No VAS data 08 = Cancel key pressed or an S00/72 reset 80 = unsupported card tapped | | 3-byte Wallet indicator | Wallet indicator shown as 3 characters | Character | 3 | APY = Apple Pay GOG = Android Pay | | | Field separator | Hexadecimal | 1 | | | {RetValString} | Return value as VAS response | | |

<9F><0A> -- 3-byte More indicator tag <9FA000ALen> -- 1-byte hex for More
indicator -- 'Y' or 'N'; 0x59 or 04E <9FA010Len> -- length of tag containing
whole json object jump <9FA0101 data> -- compressed json
object dump with stripped spaces/line feeds

| | | End of text | Hexadecimal | 1 | | | | Longitudinal Redundancy Check digit | Hexadecimal | 1 | | | **NOTE:** Valid if D41 succeeded and APPEND\_WALLETDATA = 1 | | | | | #### D41 Response Example mm/dd/yyyy 13:21:22:538 Transmit: D41B mm/dd/yyyy 13:21:22:541 Receive : mm/dd/yyyy 13:21:28:872 Receive : D4100GOG<9F><0A> <1 byte length><’Y’ or ‘N’><9F><10>\{JSON BLOB} #### D41 Additional Information: * To disable payment/NFC in XPI, POS sends 72 or S00 * The screen and text that will be displayed on a D41 command will be customizable for VAS only mode * D41 should NOT be sent separately for any request other than VAS only mode - if there is a need for payment of any kind, MSR swipe, PAN entry, EMV CTLS, or MSD contactless, or button key press, edit field entry, the D41 components should be tagged to the end of the C30 or S20 via an optional 3-byte tag <9F><0C> * D41 command has an infinite timeout by default ### D28 Retrieve Non-Payment Wallet Information Separately Transaction The D28 command is used to retrieve the non-payment wallet information separately. This command works in conjunction with the C30/S20 command. #### D28 Request Format D28 #### D28 Request Data Elements | Element | Description | Field Type | Field Length | Additional Information | | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- | ------------ | ------------ | ---------------------- | | | Start of text | Hexadecimal | 1 | | | D28 | Packet identifier/command | Alphanumeric | 3 | | | | End of text | Hexadecimal | 1 | | | | Longitudinal Redundancy Check digit | Hexadecimal | 1 | | | **NOTE:** If the data has been cleared using N72/72/S00 in the interim, then the wallet information retrieval will fail. | | | | | #### D28 Response Format <2bytelength in hex>\ #### D28 Response Data Elements | Element | Description | Field Type | Field Length | Additional Information | | --------------- | ------------------------------------------------------------------------------------------ | ------------ | ------------ | ----------------------------------------------------- | | | Start of text | Hexadecimal | 1 | | | D28 | Packet identifier/command | Alphanumeric | 3 | | | | Response code | Numeric | 2 | 00 = Wallet data follows 01 = Wallet data unavailable | | <2-byte length> | 2-byte length of rest of packet | | 2 | | | APY/GOG | 3-byte ASCII identifier for Wallet SmartTap for Google Smart Tap 2.1 wallet loyalty wallet | | 3 | | | | Field separator | Hexadecimal | 1 | 0x1C | | <9F><0A> | 3-byte More indicator tag | Hexadecimal | 3 | | | <9FA00ALen> | 1-byte length in hex for the More indicator | Hexadecimal | 1 | | | | More indicator | Alphanumeric | 1 | Y or N = 0x59 or 0x4E | | <9F><10> | Tag containing json object dump | | | | | <9FA010Len> | Length of tag containing json object dump | | | | | <9FA010 data> | Compressed json object dump with stripped spaces/line feeds | | | | | | Values of OPTFLAG | Numeric | 16 | | | | End of text | Hexadecimal | 1 | | | | Longitudinal Redundancy response | Hexadecimal | 1 | -- OK -- LRC Incorrect | #### D28 Response Example D2800<00><12>GOG<9F><0A><01><’Y’ or ‘N’><9F><10> {JSON DATA}{LRC} ### S20 Obtain Card Data Transaction (Swipe or Tap) The S20 command prompts the user for card entry via swipe or tap. Only MSD tap is supported. CVN-17 data is not returned in this command response. To obtain CVN-17 or any tag data, use the C30 card entry command. Refer to the tag 9FA00C below. | 🛈 | NOTE | Verifone strongly recommends you use the F30 instead of the S20, particularly since the EMV migration is currently taking place. Also, F30 without amount can be used, if XPI is configured for MSD. S20 should only be used by customers who have no intention of moving to EMV payments in general at the same time as making Wallet changes, and who intend to use XPI for MSD transactions. | | -- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | #### S20 Request Format S20Amount> #### S20 Request Data Elements | Element | Description | Field Type | Field Length | Additional Information | | --------------- | ------------------------------------------- | ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Start of text | Hexadecimal | 1 | | | S20 | Packet identifier/command | Alphanumeric | 3 | | | | Field separator | Hexadecimal | 1 | | | | Number of seconds time waits for card swipe | Numeric | 3 |

000 – 255 seconds
000 = no timeout, infinite wait

| | | Amount to display on terminal | Numeric | Variable | Numeric value 0.01 – 999999.99**NOTE:** Amount can be sent with or without decimal. If sent without, assume two decimal places Example: 1234 will be processed and displayed as $12.34, and 12.34 will be processed and displayed as $12.34 | | | Field separator | Hexadecimal | 1 | Optional. Sent if amount sent in next field | | 9FA00Cseparated | | | | Optional: if Wallet is enabled | | | End of text | Hexadecimal | 1 | | | | Longitudinal Redundancy Check digit | Hexadecimal | 1 | | #### S20 Response Format \\\ #### S20 Response Data Elements | Element | Description | Field Type | Field Length | Additional Information | | ---------- | ----------------------------------- | ------------ | ------------ | --------------------------------------------------------------------------------------------------------------- | | | Start of text | Hexadecimal | 1 | | | | S20 response code | Numeric | 2 | 00 = successful 01 = unsuccessful 02 = timeout occurred 03 = cancelled 90 = Vx700 external reader not available | | \ | PAN data | | | | | | Field separator | Hexadecimal | 1 | | | | ??? | Alphanumeric | variable | Track 2 data (with between tracks) Track 1 data Track 3 data | | | Swipe indicator | Numeric | 1 | 0 = swiped 1 = tapped | | | End of text | Hexadecimal | 1 | | | | Longitudinal Redundancy Check digit | Hexadecimal | 1 | = LRC OK = LRC incorrect | #### S20 Additional Information: Where 9FA00C data will look like this: 9FA00CXXXXJSON FORMATTED DYNAMIC VAS DATA REQUEST PARAMETERS Refer to *For detailed information on* the C32, C34, and C36 transactions, please refer to the *External PINPad Interface* guide. D41 VAS Only Transaction and C30 Enable Card Insertion for more details on json Formatted Dynamic VAS Data Request Preload Parameters. Where 9FA00C data will look like this: 9FA00CXXXXDISCOVERY\_TYPE=POSTTXN|POSDATA TERM\_CAP={terminal-capabilities} CUST\_DATA={customer-data} MERCHANT\_INDEX={merchant-index-list} CMD\_OPTS={command-options} DATA={dynamic-data} | | **IMPORTANT:** These commands are for reference only to illustrate the logic. Tags & lengths will be different in your environments. | | - | ------------------------------------------------------------------------------------------------------------------------------------ | ### D50 Upload/Download Configuration File The D50 command is used to upload or download the configuration files used in CAM. #### D50 Request Format D50 #### D50 Request Data Elements | Element | Description | Field Type | Field Length | Additional Information | | ------- | ----------------------------------- | ------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Start of text | Hexadecimal | 1 | | | D50 | Packet identifier/command | Alphanumeric | 3 | | | | Field separator | Hexadecimal | 1 | | | | Length of | Hexadecimal | 2 | Maximum: 65,535 bytes | | | Parameters in TLV format | Hexadecimal | |

These are the Custom Tags:
DFE001 – File Name DFE002 – File Operation DFE003 – File Checksum DFE004 – Size of data DFE005 – Total file size DFE006 -- Data

| | | End of text | Hexadecimal | 1 | | | | Longitudinal Redundancy Check digit | Hexadecimal | 1 | = LRC OK = LRC incorrect | **Custom Tags (Request)** DFE001 – File Name DFE002 – File Operation * 01 – Create new file (overwrites existing file) * 02 – Append data * 03 – Read data | 🛈 | NOTE | For VOS2, the File Operation 01 (Create new file) and 02 (Append data) are permitted only in files within the flash memory. | | -- | ---- | --------------------------------------------------------------------------------------------------------------------------- | DFE003 - File Checksum * 20-byte checksum calculated using SHA-1. This is to make sure that the file is a 1:1 copy * Checksum will be calculated on the final D50 request for File Operation 02 DFE004 - Size of Data * For File Operations 01 or 02, this is the Size of Input Data (Tag DFE006) * For File Operation 03, this is the total size of data received so far, which will indicate the file offset to start/continue reading data DFE005 - Total File Size (Only for File Operations 01 or 02) DFE006 - Input Data (Only for File Operations 01 or 02) #### D50 Response Format The response is returned on the final D50 request for File Operation 02. The response is also returned on every D50 request for File Operation 03. D50 #### D50 Response Data Elements | Element | Description | Field Type | Field Length | Additional Information | | ------- | ----------------------------------- | ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Start of text | Hexadecimal | 1 | | | D50 | Packet identifier/command | Alphanumeric | 3 | | | | D50 response code | Alphanumeric | 2 | 00 = successful 01 = file operation failed 02 = invalid format 03 = file not found 04 = checksum error | | | Length of | Hexadecimal | 2 | Maximum: 65,535 bytes Return on if File Operation = 3 | | | Parameters in TLV format | Hexadecimal | |

Returned only if File Operation = 3 These are the Custom Tags:
DFE003 – File Checksum DFE004 – Size of data DFE005 – Total file size DFE006 -- Data

| | | End of text | Hexadecimal | 1 | N/A | | | Longitudinal Redundancy Check digit | Hexadecimal | 1 | = LRC OK = LRC incorrect | **Custom Tags (Response)** DFE003 - File Checksum of config file (Only for File Operation 03) * 20-byte checksum calculated using SHA-1 * Returned if DFE006 contains the final chunk of data DFE004 - Size of Data (Only for File Operation 03) * This is the Size of Input Data * For File Operation 03, this is the total size of data received so far, which will indicate the file offset to start/continue reading data DFE005 - Total File Size (Only for File Operation 03) DFE006 - Input Data (Only for File Operation 03 Chapter 4 – 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"). ### 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. ### 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 5, 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/5c14d704365675e6a16bc9191f886812a32c60d4) Figure 5 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) The following is an example of the D41 with VAS URL: D41{"Preload\_Configuration":{"Configuration\_version":"1.0","Terminal":{"Terminal\_Capabilities":{"Capabilities":"VAS"},"PollTech":"AB","PollTime":15000,"Source\_List":\[{"Source":"ApplePay" }]},"Wallet":{"Cmd\_Opts":{"Cmd\_Type":"Push","Auth\_Param":0,"Encr\_Param":0},"Push\_Data":{"Customer\_Data":\[{"Type":"DU","Value":" [www.dutest.com](http://www.dutest.com/)"}]}}}} ### Sample C30 Wallet Command This section shows a sample C30 command (VAS only) with the preload information using Apple VAS 2.0. | | IMPORTANT | These commands are for reference only to illustrate the logic. Tags & lengths will be different in your environments. | | - | --------- | --------------------------------------------------------------------------------------------------------------------- | **VAS Command** C30$D1<9F><0C><81>{"Preload\_Configuration":{"Configuration\_version":"1.0","Terminal":{"Terminal\_Capabilities":{"Capabilities":"VAS"},"PollTech":"AB","PollTime":15000,"Source\_List":\[{"Source":"ApplePay"}]}}} **Command Response** C3121<9F><82><9B>APY<9F>N<9F><82><8B>{"Source":"ApplePay","Mobile\_App\_Version":"0100","Merchant\_Name":"VerifoneQA","Merchant\_Id":"Jenny8675309","Services":\[{"is\_encrypt":0,"Service\_ID":"pass.com.verifone.generic.test1","Service\_Type":"ABCRewards","Status\_Word":"6a83"},{"is\_encrypt":0,"Service\_ID":"pass.com.genericmerchant.y2y","Service\_Type":"GenericMerchantRewards","Status\_Word":"6a83"},{"is\_encrypt":0,"Service\_ID":"pass.com.apple.wallet.vas.prodtest","Service\_Type":"BetaCoupon","Status\_Word":"6a83"},{"is\_encrypt":0,"Service\_ID":"pass.com.apple.wallet.dev.alphamerchant","Service\_Type":"AlphaCoupon","Status\_Word":"6a83"},{"is\_encrypt":1,"Service\_ID":"pass.com.verifone.test.B","Service\_Type":"EncryptedCoupon","Status\_Word":"9000","VAS\_Data":"416c706861315f31323334353637","encrypt\_vas\_data":"fe65014eadd82074d4640ac6602bfe9cb1acc9584c64820e56a661fd8327121039a34c1c5cdf22331a17513d01ceb9fc4dc1a13022c083f5ea895f852135ab57416bd1785197","cipher\_time\_stamp":"20a1e959"}]} #### 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 6 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 CXPI.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/a8e937db2f738f2d555e19b9e7d012f56785f405) Figure 6 Requesting Apple Public, Private & Wallet Keys #### Apple VAS Decryption The example (VAS only) below shows how Apple VAS decryption works. C3121<9F><82><9B>APY<9F>N<9F><82><8B>{"Source":"ApplePay","Mobile\_App\_Version":"0100","Merchant\_Name":"VerifoneQA","Merchant\_Id":"Jenny8675309","Services":\[{"is\_encrypt":0,"Service\_ID":"pass.com.verifone.gap.test1","Service\_Type":"GapRewards","Status\_Word":"6a83"},{"is\_encrypt":0,"Service\_ID":"pass.com.kohls.y2y","Service\_Type":"ABCStoreRewards","Status\_Word":"6a83"},{"is\_encrypt":0,"Service\_ID":"pass.com.apple.wallet.vas.prodtest","Service\_Type":"BetaCoupon","Status\_Word":"6a83"},{"is\_encrypt":0,"Service\_ID":"pass.com.apple.wallet.dev.alpha","Service\_Type":"BetaCoupon","Status\_Word":"6a83"},{"is\_encrypt":1,"Service\_ID":"pass.com.verifone.test.B","Service\_Type":"EncryptedCoupon","Status\_Word":"9000","VAS\_Data":"416c706861315f31323334353637"," encrypt\_vas\_data":"fe65014eadd82074d4640ac6602bfe9cb1acc9584c64820e56a661fd8327121039a34c1c5cdf22331a17513d01ceb9fc4dc1a13022c083f5ea895f852135ab57416bd1785197","cipher\_time\_stamp":"20a1e959"}]} Below is the hex to ASCII conversion: 416c706861315f31323334353637 = Alpha1\_1234567 ### 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, etc * 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/7943fd587073c960ab91aaec8b3d873dbd65df98) Figure 7 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 | Chapter 5 – 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 GooglePay (no space between before "Pay"). This document references Google Smart Tap 2.1 (for Android Pay / Google Pay). | 🛈 | NOTE | 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. | | -- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ### Invoking Google json Preload C30$D1<9F><0C><82>{"Preload\_Configuration":{"Configuration\_version":"1.0","Terminal":{"PollTech":"AB","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":"Get","Auth\_Param":1,"Encr\_Param":1},"Service\_Type\_List":\[{"Service\_Type":"Coupon"},{"Service\_Type":"Loyalty"}]}}} ### 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 D41 secure PUSH command. D41{"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. ### Sample Wallet Command This section shows a sample C30 command (VAS only) with the preload information using Google Smart Tap 2.1. | | IMPORTANT | These commands are for reference only to illustrate the logic. Tags & lengths will be different. | | - | --------- | ------------------------------------------------------------------------------------------------ | **C30 Command** C30\&G1<9F><0C><82><87>{"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","Auth\_Param":0,"Encr\_Param":0},"Service\_Type\_List":\[{"Service\_Type":"EncryptedCoupon"},{"Service\_Type":"Coupon"},{"Service\_Type":"Loyalty"}]}}} **C30 Command Response** C3121 <82>GOG<9F>N<9F><82>{"Format\_Version":"1.0","Source":"AndroidPay","Mobile\_App\_Version":"1","Merchant\_Name":"Google\_EncryptedCoupon","Merchant\_Id":"12345678","Min\_App\_Version":"0","Max\_App\_Version":"1","Services\_List":\[{"Service\_Issuer":"Merchant Issued","Service\_Issuer\_Id":"00bc614e","Services":\[{"Service\_Type":"Loyalty","Service\_Object\_Id":"72ac07dbac6a8167","Service\_Number":"999999"},{"Service\_Type":"Loyalty","Service\_Object\_Id":"905b42e96a3dd404","Service\_Number":"GFUS\@420"}]}]} ### 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/a02fd9a0d974cf15e54c607d73bf55842952cdaf) Figure 8 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/86a2644985d7269f0fe641121e366a7943f1c12b) Figure 9 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/721d1cd56d63d878c9098ff520966cd734e9a1f6#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/721d1cd56d63d878c9098ff520966cd734e9a1f6#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/721d1cd56d63d878c9098ff520966cd734e9a1f6#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/721d1cd56d63d878c9098ff520966cd734e9a1f6#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/721d1cd56d63d878c9098ff520966cd734e9a1f6#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/721d1cd56d63d878c9098ff520966cd734e9a1f6#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/721d1cd56d63d878c9098ff520966cd734e9a1f6#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/721d1cd56d63d878c9098ff520966cd734e9a1f6#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/721d1cd56d63d878c9098ff520966cd734e9a1f6#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/721d1cd56d63d878c9098ff520966cd734e9a1f6#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/721d1cd56d63d878c9098ff520966cd734e9a1f6#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/721d1cd56d63d878c9098ff520966cd734e9a1f6#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/721d1cd56d63d878c9098ff520966cd734e9a1f6#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/721d1cd56d63d878c9098ff520966cd734e9a1f6#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/721d1cd56d63d878c9098ff520966cd734e9a1f6#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/721d1cd56d63d878c9098ff520966cd734e9a1f6#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/721d1cd56d63d878c9098ff520966cd734e9a1f6#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/721d1cd56d63d878c9098ff520966cd734e9a1f6#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" | Keeps an optional json object that represents customer information | | "Service\_Issuer\_Id" | | | | | | | "Services" | | | | | | | "Service\_Issuer" | M | "Services\_List" | String (ASCII) | Variable | [Service Issuer](broken://pages/721d1cd56d63d878c9098ff520966cd734e9a1f6#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" | Array of services | | "Service\_Object\_Id" | | | | | | | "Service\_Number" | | | | | | | "Expiration" | | | | | | | "CCV1" | | | | | | | "Track1" | | | | | | | "Track2" | | | | | | | "PIN" | | | | | | | "Customer" | | | | | | | "Service\_Type" | M | "Services" | String (ASCII) | Variable | [Service Types](broken://pages/721d1cd56d63d878c9098ff520966cd734e9a1f6#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" | Keeps an optional json object represents customer information | | "Wallet\_Issuer" | | | | | | | "Customer\_Name" | | | | | | | "Tap\_Id" | | | | | | | "Mobile\_Device\_Id" | | | | | | | "Customer\_Email" | | | | | | | "Preferred\_Language" | | | | | | | "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 – Calculating C30 with Tags & Lengths When structuring the VAS commands, the tags and lengths need to be correct for the command to execute properly. This appendix explains how to calculate the tag and lengths and convert to hexadecimal. ### Original Wallet C30 Command C30$D1<9F><0C><82>{"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":"Get","Auth\_Param":1,"Encr\_Param":1},"Service\_Type\_List":\[{"Service\_Type":"Coupon"},{"Service\_Type":"Loyalty"}]}}} ### Instructions The parts highlighted in yellow require two updates: * After the C30 command for the length of the tags * At the end, prior to json changes ("Preload\_Configuration") The parts highlighted in green are the changes we are making that require a new tag length. In this example, we will be editing the "Service\_Type\_List" and changing the "Service\_Type" from "Coupon" to "WalletCustomer". To complete this task, you will need to use a decimal to hexadecimal conversion tool or a chart like the one shown in Figure 10. #### Length Change Step 1 * Start with "Coupon" at 6 bytes and change to "Wallet Customer" at 15 bytes, gives us an additional 9 bytes * Total length = STX (2) + E5 (229) = 231 * However, you can ignore STX, since the length is below 256 * Since the difference between "Coupon" (6 bytes) and "Wallet Customer" (15 bytes) = 9 bytes, that correlates to 229 + 9 = 238 (decimal) = ee (hexadecimal) #### Length Change Step 2 * Total length = ETX (3) + CR (13) = 16 * However, you can ignore ETX, since the length is below 256 * To add "Wallet Customer" to json, you add 9 bytes to 13 = 22 (decimal) = 16 (hexadecimal) ### Updated Wallet C30 Command C30<16>$D1<9F><0C><82>{"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":"Get","Auth\_Param":1,"Encr\_Param":1},"Service\_Type\_List":\[{"Service\_Type":"WalletCustomer"},{"Service\_Type":"Loyalty"}]}}} ![](/files/076efb4523141ee78d23d5477ac1250f69b5aeb4) Figure 10 Decimal to Hexadecimal Conversion Chart Appendix C – 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/xpi/tbd-documentation/mobile-wallets/xpi-mobile-wallet-setup-guide-1_4.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.