# NewTemp\_XPI\_Mobile\_Wallet\_Apple\_VAS2.0\_SetupGuide1.2 ## 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 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 manual, you may encounter the following text boxes. These are meant to draw your attention to certain concepts and are easily identifiable by their icons. | ![](/files/911e501a81ff61a0548ec26c0561929793362347)**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. | | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ![](/files/54d1f5a56f7841a588e94741eab73124bbd853ad)**WARNING** | We **HIGHLY** recommend that you read ALL warnings in the sections of the manual that you read. These warnings will help to prevent serious issues from occurring. | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ![](/files/26c7c6aacfb1fce633dc4bfa5d4c52c6d6bd0f87)**CAUTION** | The caution symbol indicates possible hardware or software failure, or loss of data. | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------ | #### 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 | This is associated with the specific merchant identifier stored as Service Id for Apple VAS 2.0. | | 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 | | 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 and the payment terminal | | XPI | External PIN Pad Interface | | wky | Wallet Key File – the Wallet Key json file stored on the payment terminal | #### Data Types and 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/M | Required/ Mandatory – required in all cases | | O | Optional – required in no cases | | C | Conditional – required in some cases | ## Chapter 2 - Overview Apple VAS 2.0 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". Mobile Wallet technology links a pass (Apple) 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 enrol customers into a loyalty program during a purchase Figure 1 shows a high-level overview of Wallet VAS. ![](/files/b0bcdc0252a26c9d58d41923aa16c03e2b1debeb) 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. #### 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 in customers' mobile wallet applications. Customers can set default passes to use for loyalty and payment providers. This means, when a customer enters a store and has that store's loyalty card pass 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-Enrolment This technology allows for a consumer who is not already enrolled into a loyalty program to 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 enrolment into the loyalty program. #### Card and Payment Types Mobile Wallet VAS works with private label cards, loyalty/reward cards, gift cards, event tickets 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. Apple VAS 2.0 use key management, a payment terminal feature, to authenticate the terminal and to encrypt the data. The wallet key provider will provide mobile pass 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 and 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 | | ![](/files/911e501a81ff61a0548ec26c0561929793362347)**NOTE** | VSS scripts for Wallet will remain on 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. | ![](/files/911e501a81ff61a0548ec26c0561929793362347)**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. For the payment application used on Engage devices, the wallet keys are stored in the flash directory in config.usr1 (/home/user1/flash). When a new wallet key is generated, it is encoded as 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. 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. Refer to [APPLE.wky File](#_APPLE.wky_File) and [Apple Keys](#_Apple_Keys)\_\_for more information on wallet 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. Refer to [Terminal json File](#_Terminal_json_File) for more details. 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. Refer to [Appendix A](#AppendixA)\_\_for examples of these files. The current loyalty and offer interface support Apple VAS 2.0. 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": "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 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. | ![](/files/911e501a81ff61a0548ec26c0561929793362347)**NOTE** | For Engage devices, the contactless kernel is part of the ADK. | | ------------------------------------------------------------ | -------------------------------------------------------------- | | ![](/files/911e501a81ff61a0548ec26c0561929793362347)**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. | Software Component | Software Version | | -------------------------------- | ----------------------------------- | | Operating System | 30810600 | | ADK | 4.4.16.1 | | XPI (*Minimum required version*) | 19.01.18.00 | | XPI (*Current versions*) | 19.03.05 20.00.16 19.04.xx 20.04.xx | #### 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. ### Hardware You can set up and use XPI Mobile Wallet VAS on the Engage devices, with ADK 4.6.0, as shown in Figure 2 Engage Devices. | ![](/files/911e501a81ff61a0548ec26c0561929793362347)**NOTE** | The PIN Pads must have more than 64 MB of RAM for Mobile Wallet VAS to work (for VHQ and ADK). | | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | Following devices are supported for XPI Mobile Wallet VAS. | Supported Engage Devices | | ----------------------------------------------------------------------------------------------------------- | | **e280**\*\*![](/files/ab2b2c3239e2e97d0ad0e26b881416caca110b8a)\*\* | | **P400**\*\*![P400.jpg](/files/d12ae7df7fca16ce595f4a7724984737eab5a8e5)\*\* | | **V200c**\*\*![v200c\_front\_screen\_3118 × 4536](/files/db9d4810ff01a8a8eea6a0020a3f39e49bd379fa)\*\* | Figure 2 Engage 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. Refer to [Terminal json File](#_Terminal_json_File) to see a sample file. #### VAS or Payment In **VAS or Payment** mode, the behavior is dependent on the VAS transaction response and the NFC kernel that is used. #### VAS and Payment The VAS and Payment mode is the default 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. #### VAS Only In this mode, only VAS data is transmitted. If you will be using this mode, 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, it is recommended to 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, it is suggested to 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, follow your existing Verifone production support processes. ## Chapter 3 - Processing XPI Commands ### XPI Platform Components As Figure 3 illustrates, the Engage solution uses common, re-usable building blocks deployed as one application. ![](/files/53a0d964841627cf1c8632af4cd2f920d02324b0) Figure 3 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 * D42 – Returns the VAS configuration * D50 – Upload and download configuration file | ![](/files/911e501a81ff61a0548ec26c0561929793362347)**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 Quick Chip and non Quick Chip transactions. This command combines the traditional C30, C32, C34, C36, I02, E07, E02, and the E05 command. 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 10 - previous step missing 11 - response has more packets
12 - When Generate AC response is a failure and a magnetic swipe is needed. 51 - VAS and Payment; both happen 52 - VAS or payment; VAS happens 56 - VAS fail 70 - N/A: WIC Card inserted
71 - APM Selection 72 - APM transaction processed 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) 92 - Bad Swipe 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 | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | <9C> | Transaction Type This tag is used to indicate the transaction type for both CT and CTLS transactions. ‎ If transaction type is not specified, 0x00 is taken as the default transaction type. | | <9F><30> | Timeout Default value is infinite timeout for EMV Contact and 256 seconds if EMV CTLS is used. | | <9F><33> | Terminal Capabilities This is used to override terminal capability no matter what AID is finally selected (it also overrides any U01 or preferredAIDs.ini imposition – this is done before GPO). | | <9F><03> | Amount Other Example: <9F><03> : <9F><03><06><00><00><00><00><10><00> | **Custom Tags** | Tag Name | Description | | -------- | ----------------------- | | <9F><0C> | Wallet input parameters | Response Format Tags **Default EMV Tags Returned** | Tag Name | Description | | -------- | ---------------------------------------------------------------------------------------------------- | | <84> |

Dedicated File (DF) Name
NOTE: The AID is returned in tag 84, not tag 4F.

| | <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".
  • <9FA011Len>BERTLV Tag Length for the type of wallet tap
  • <9F><11> Tag containing "APY".
| | <9F><34 | Verifone custom EParms 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 | | ![](/files/911e501a81ff61a0548ec26c0561929793362347)**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. | | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | F30 Response for Base64 Response on Large VAS Data In specific wallet test cases where the F30 Base64 response data exceeds the allocated buffer size, which is 4096 bytes, the VAS data is split into multiple VAS data packets. Response code 88 is used and the <9F><0A> tag is set to indicate if there are more data. The remaining VAS data is then sent in another F30 response. For example, if a Base64 response data is split into three replies, the first two replies are F3088, the final is F3000. Each reply has the <9F><0A> tag. The first two replies have ‘Y’ as the value which indicates yes, there is more data. The final reply has ‘N’ as the value which indicates NO, there is no more data. See this example: **First:** **F3088**n6ARA0dPR5+gCgFZ Base64 Decode (Hex): <9F><11><03>”APY” + <9F><0A><01><’**Y**’> **Second:** **F3088**n6ARA0dPR5+gCgFZ Base64 Decode (Hex): <9F><11><03>”APY” + <9F><0A><01><’**Y**’> **Third:** **F3000**n6ARA0dPR5+gCgFZ Base64 Decode (Hex): <9F><11><03>”APY” + <9F><0A><01><’**N**’> | ![](/files/911e501a81ff61a0548ec26c0561929793362347)**NOTE** |
  • The same principle of splitting large amount of VAS data applies to the other F30 responses if there is large amount of data from the passes. However, this process do not apply to the C31 responses for wallet data.
  • When CAM-XPI is in the process of sending the multiple responses to the POS or to the calling application, the POS or the calling application should stop sending commands to CAM-XPI until the full payload has been received.
| | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ### C30 - Enable Card Insertion The C30 command is used to prompt for card insertion. 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 NOTE\*\*:\*\* This is optional and only applies to EMV CTLS. | | 9FA00C |

D41 components as defined in D41 command.
Where, 9FA00C data will look like: 9FA00CXXXXJSON FORMATTED DYNAMIC VAS DATA REQUEST PARAMETERS

| C30 Response Format **C31** C30 Response Data Elements | Element | Description | Field Type | Field Length | Additional Information | | ------- | -------------------------------- | ------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Start of text | Hexadecimal | 1 | | | C31 | Packet identifier/command | Alphanumeric | 3 | | | | 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
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 | Refer to the *External PINPad Interface* *Functional Specification* guide\_,\_ for detailed information on the C32, C34, and C36 transactions. C30 Response Format 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
| | <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".
  • <9FA011Len>BERTLV Tag Length for the type of wallet tap
  • <9F><11> Tag containing "APY".
| Sub-tag C3 for MasterCard Value-Added Services (VAS) The new MasterCard VAS tags must be returned to the ECR. The XPI messaging between the ECR and the PIN pad will be enhanced. These are the additional information required by the ECR for the MasterCard VAS transaction: * Device ID of the Mobile Phone that the points were redeemed. * Points redeemed. These new values will be obtained as part of the Card Entry process (C30 command) and will be returned in the C31 response. The application will be modified to add a new sub-tag C3 as part of the tag response data in the C31 response that will include these new tags. The C3 sub-tag will be included after the C2 sub-tag values. Refer to *External PINPad Interface Guide*, for more details on C2 tag. See example below: | **Response Format:** | | | | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | --- | | C3121<0x00><0x74><0xC2><0x28>374245\***0001=150770209114992000053?. ?%B3742454**\*\*^XP2 Card 700053^1507702091149920?.<9F>9<91> MCV<9F><9FF0Len><9F><9FF1len> | | | | Elements: | | | | | | 1H | | | | 3AN | | | | 1H | | | MCV | 3AN | | | <9F> | 2H | | | <9FFALen> | 1H | | | | 10H | | | <9F> | 2H | | | <9FF1Len> | 8H | | | | 8H | There will be no changes to the C31 response format. The change will apply to the one field for the to include the C3 tags as described on the previous page. If the user selects the VAS AID on the Phone, but no points redeemed, then the tag 9FFO and 9FF1 tags in the tag C3 will still be returned, but with a of zero. If there is an error in selecting the payment card, the error will be returned with the C30. Since there might be MCVAS data being returned even though there was issue selecting the card, that data will be returned in the C31 response, along with the error. The MCVAS AID is constant and is only used to identify that an MCVAS-capable card or device is being presented to the reader. By configuring, it we would be indicating that MCVAS is a payment card. Sending the D40 will allow us to enable/disable the MCVAS AID by setting the <9FF0Data> tag to the appropriate value. There is no actual way to query the status of MCVAS to check if it has been turned on or off, but if we are deactivating MCVAS all other tags (9FF1, 9FF2, 9FF3, 9FF4, 9FF5, and 9FF6) can be omitted. Expired flag and cardholder language flag will be tied strictly to the magstripe (3121) since tag 95 already provides details on the expired application in the case of EMV. The cardholder language flag would not apply to the US, so we would need to keep it tied to the country code. Language is the last byte on the discretionary data, 1 being English and 2 French. C30/S20 - Activate Transaction Response for Payment and/or VAS To activate transaction for payment and/or VAS, existing C30 or S20 command will be used. After tap, the information will be sent back to POS in C31 or S20 response. Refer to the XPI specification document for detailed explanation of the payment portion of the commands. Note the D41 “tag” that can be added to the C30/S20 requests. For example, if {terminal-capabilities} in D41 9FA00C tag in C30/S20 extended - has a value of VAS and Payment, and configuration variable \[iab] APPEND\_WALLETDATA=1, payment and loyalty data are obtained in this one-step process. **Option 1:** The payment and the non-payment wallet data, all is sent in the C31/S20 response. This is a single tap scenario. C3 tag and data below denotes the NFC tap non-payment data. **Option 2:** The payment data from the tap is sent in the C31 or S20 response, to be followed by a D28 for the non-payment wallet data retrieval. If the POS does not wish to receive the wallet data, then POS does not have to issue the D28. Note the “51” and “52” indicator codes. For example, if {terminal-capabilities} in D41 9FA00C tag in C30/S20 extended - has a value of VAS and Payment, and configuration variable \[iab] APPEND\_WALLETDATA=0, the payment below and loyalty data are obtained in this one-step tap process, but two-step POS request process. ### 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 **D41**JSON FORMATTED DYNAMIC VAS DATA REQUEST PARAMETERS Refer to [Appendix A](#AppendixA) 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 **D41**RetVal<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 | 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 | | | 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 D4100\~APY<9F>N<9F>o{"Source":"ApplePay","Merchant\_Name":"Macy's","Merchant\_Id":"A1B2C3D4","Mobile\_App\_Version":"0100","Services":\[ {"Service\_ID":"pass.com.apple.wallet.vas.prodtest","Service\_Type":"Coupon","Status\_Word":"9000","VAS\_Data":"9af30339b977503f4e5431dde1dcb0e7290f388c2f56fd64b2776ccfac801dfbdc00a7a83c6b333484dbbaa0fa236a412039eece2a584a4caa482bc5c3b0a4450f005879902a9448"} ]} 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. | ![](/files/911e501a81ff61a0548ec26c0561929793362347)**NOTE** | This command is required to be used only if append\_walletdata is set to 0. | | ------------------------------------------------------------ | --------------------------------------------------------------------------- | 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 | 3-byte ASCII identifier for 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}APY<9F>N<9F><82>m{"Source":"ApplePay","Format\_Version":"1.0","Mobile\_App\_Version":"1","Merchant\_Name":"Merchant\_Name-1","Merchant\_Id":"12345678","Min\_App\_Version":"0","Max\_App\_Version":"1","Services\_List":\[{"Service\_Issuer":"Merchant Issued","Service\_Issuer\_Id":"79798","Services":\[ {"Service\_Type":"Loyalty","Service\_Object\_Id":"0df719f69c6aec74","Service\_Number":"324234234"} ]}]} ### 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. | ![](/files/911e501a81ff61a0548ec26c0561929793362347)**NOTE** | Verifone strongly recommends the user to use F30 command instead of the S20 command, 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 **S20**Amount> 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 | | | | When 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 - cancelled56 - VAS Fail 80 - PIN pad beeps tick and goes back to IDLE screen. 92 - BAD\_SWIPE | | \ | 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 the following: 9FA00CXXXXJSON FORMATTED DYNAMIC VAS DATA REQUEST PARAMETERS Refer to *External PINPad Interface Guide*, for detailed information on the C32, C34, and C36 transactions. Refer to [Apple VAS 2.0](#Chapter4) for more details on json Formatted Dynamic VAS Data Request Preload Parameters. Where 9FA00C data will look the following: 9FA00CXXXXDISCOVERY\_TYPE=POSTTXN|POSDATA TERM\_CAP={terminal-capabilities} CUST\_DATA={customer-data} MERCHANT\_INDEX={merchant-index-list} CMD\_OPTS={command-options} DATA={dynamic-data} | ![](/files/911e501a81ff61a0548ec26c0561929793362347)**NOTE** | These commands are for reference only to illustrate the logic. Tags and lengths will be different in your environments. | | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | S20 Response Format 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
| | <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".
  • <9FA011Len>BERTLV Tag Length for the type of wallet tap
  • <9F><11> Tag containing "APY".
| ### D42 - Returns the VAS Configuration The D42 command is used to fetch the data of the VAS configuration of the terminal. D42 Request Format **D42** D42 Request Data Elements | Element | Description | Field Type | Field Length | Additional Information | | ------- | ----------------------------------- | ----------- | ------------ | ------------------------ | | | Start of text | Hexadecimal | 1 | | | D42 | Packet identifier/command Code | | | | | | End of text | Hexadecimal | 1 | | | | Longitudinal Redundancy Check digit | Hexadecimal | 1 | - LRC OK - LRC incorrect | D42 Response Format **D42** D42 Response Data Elements | Element | Description | Field Type | Field Length | Additional Information | | ------- | ----------------------------------- | ----------- | ------------ | --------------------------------------------------------------------------------------------------- | | | Start of text | Hexadecimal | 1 | | | D50 | Packet identifier/command Code | | | | | | D42 response code | Numeric | 2 | 00 - Successful 01 - Failed 02 - No VAS Configuration Data 88 - More VAS Configuration will be sent | | | Field Separator | | | | | | Length of in ASCII Decimal Number | | Variable | | | | Field Separator | | | | | | VAS Configuration Data | | Variable | | | | End of text | Hexadecimal | 1 | N/A | | | Longitudinal Redundancy Check digit | Hexadecimal | 1 | - LRC OK - LRC incorrect | D42 Response Example D42001816{"Format\_Version":"1.0","App\_Id":"CXPI","VAS\_Configuration":\[{"Source":"ApplePay","Protocol\_Name":"applepay\_vas","Pre\_Load":"false","terminal\_caps":"Payment\&VAS","App\_ID":"CXPI","Protocol\_Version":"0100","Wallet\_Config\_version":"1.0","Configuration\_version":"1.0","CustomPollData":"80 10 81 10 60 10 08 08 05 6A 01 00 00 01","Merchant": {"Merchant\_Name":"VerifoneQA","Merchant\_Id":"Jenny8675309"} ,"Cmd\_Opts": {"Cmd\_Type":"GET"} ,"Services":\[ {"Service\_Type":"Coupon1","Service\_ID":"pass.com.apple.wallet.vas.prodtest","Service\_Issuer":"Apple","URL":"[www.appleprodtest.com","Vas\_Filter":"01](https://docs.verifone.com/xpi/tbd-documentation/mobile-wallets/http:/www.appleprodtest.com","Vas_Filter":"01) 00 00 00 00"} , {"Service\_Type":"Coupon2","Service\_ID":"pass.com.apple.wallet.dev.panera","Service\_Issuer":"Apple","URL":"[www.merchant2.com","Vas\_Filter":"01](https://docs.verifone.com/xpi/tbd-documentation/mobile-wallets/http:/www.merchant2.com","Vas_Filter":"01) 00 00 00 00"} , {"Service\_Type":"Coupon3","Service\_ID":"pass.com.apple.test1","Service\_Issuer":"Apple","URL":"[www.merchant3.com","Vas\_Filter":"01](https://docs.verifone.com/xpi/tbd-documentation/mobile-wallets/http:/www.merchant3.com","Vas_Filter":"01) 00 00 00 00"} ],"key\_list":\[\["pass.com.apple.test1","9903dd05","2017-04-07T14:24:00Z","82E71F"]],"timestamp\_diff":10},{"Get\_Config\_Version":"1.0","Pre\_Load":"false","VWI\_Wallets":\[{"Source":"ApplePay","Protocol\_Name":"VWI\_Kernel","Protocol\_Version":"0001","Wallet\_App\_Version":0,"APDU\_Max\_Len":255,"AutoPay":"false","Services":\[ {"Service\_Type":"PLC"} , {"Service\_Type":"Loyalty"} , {"Service\_Type":"Coupon"} , {"Service\_Type":"Gift Card"} , {"Service\_Type":"Wallet Customer"} , {"Service\_Type":"ALL"} , {"Service\_Type":"All except PPSE"} ],"Cmd\_Opts": {"Cmd\_Type":"Get","Auth\_Param":1,"Encr\_Param":1} ,"Merchant": {"Merchant\_Name":"Merchant\_Name-1","Merchant\_Id":"12345678","Merchant\_Type":"Merchant\_Type-1","Terminal\_Id":"A01234C1","Store\_Id":"A01234D1"} ,"AIDs":\[ {"aid":"a000000476d0000111"} ],"key": {"merchant\_id":"12345678","key\_version":"9903dd05","kbpk\_Id":"82E71F","key\_time\_stamp":"2017-09-12T14:24:00Z"} ,"terminal\_caps":"Payment\&VAS"}]}]}\[ ### D50 - Upload/Download Configuration File The D50 command is used to upload or download the configuration files used in CAM.On VOS/VOS2, files can be written under /**mnt/flash**. This command can be used to push the CXPI JSON files. 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 DFE007 - Apply File configuration (Optional)

| | | End of text | Hexadecimal | 1 | | | | Longitudinal Redundancy Check digit | Hexadecimal | 1 | = LRC OK = LRC incorrect | Custom Tags (Request) * **DFE001** - File Name. This can also include the path.For example: flash/EMVTABLES.INI | ![](/files/911e501a81ff61a0548ec26c0561929793362347)**NOTE** |

If a path is not specified when sending files, then the file will be saved on the location where CAM is installed.
If the path is not specified when retrieving files, then the file that is being retrieved is stored on the location where CAM is installed.
For example: In VOS/VOS2, if CAM is installed in usr1, the file will be automatically saved or retrieved in /home/usr1/.

| | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | * **DFE002**- File Operation * 01 - Create new file (overwrites existing file) * 02 - Append data * 03 - Read data * 04 - Apply EMV Configuration | ![](/files/911e501a81ff61a0548ec26c0561929793362347)**NOTE** |

If DFE002 tag is set to 04, then it will apply EMV configuration from INI files: EMVTABLES.INI, CTLSCONFIG.INI, CAPKDATA.INI and CTLSCAPKDATA.INI files.
If none of these INI files are present, then D50 will fail.

| | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ![](/files/911e501a81ff61a0548ec26c0561929793362347)**NOTE** |
  • For VOS and VOS2, the File Operation 01 (Create New File) and 02 (Append Data) are permitted only in files within the flash memory.
  • File Operation 01 (Create New File) and 02 (Append Data) are used for the D50 to send files. File Operation 01 and 02 are applicable only to files or path with Write permission, otherwise, an error may occur.
  • File Operation 03 (Read Data) is used for the D50 to retrieve files.
| | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | * **DFE003** - File Checksum * 20-byte checksum calculated using SHA-1. This is to ensure 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. **DFE004** should be present in D50 Input Request for File operation 03. * **DFE005** - Total File Size (Only for File Operations 01 or 02) * **DFE006** - Input Data (Only for File Operations 01 or 02) * **DFE007** - Apply File configuration. Optional tag. If this tag is set to 01 or enabled, the configuration data saved in the file will be applied to the ADK EMV framework. This tag is only applicable to the following files: * EMVTABLES.INI * CTLSCONFIG.INI * CAPKDATA.INI * CTLSCAPKDATA.INI 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 size of output data * **DFE005** - Total File Size (Only for File Operation 03) * **DFE006** – Output 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 enrolment 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 4, 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/11b78804dc4cdffe5aab064d0501a18d5ceff235) Figure 4 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. | ![](/files/911e501a81ff61a0548ec26c0561929793362347)**NOTE** | These commands are for reference only to illustrate the logic. Tags and 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 and Wallet Keys The following is a high-level overview on how a merchant requests a public, private, and wallet keys from Apple. This process will take a few days. See Figure 5 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’s 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](#AppendixA)\_\_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/b1e6895f59c4892b046e937231ccd257b5f71ecb) Figure 5 Requesting Apple Public, Private and 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/dda2139497eb58cd008ea14fed965b140c17fba8) Figure 6 Apple VAS 2.0 VAS Kernel Architecture #### Data Rules | Element | Description | | ------- | ---------------------------------------------------------- | | R / M | Required / Mandatory – required in all cases | | O | Optional – required in no cases | | C | Conditional – will be included if configured and/or exists | #### SW1 and 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 | ## 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" } }, | ![](/files/911e501a81ff61a0548ec26c0561929793362347)**NOTE** | The above configuration method is recommended to enroll a customer using a VAS push command with dynamic data from the POS, like a phone number or loyalty number. | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ### 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" } ] } } ## Appendix B - Calculating C30 with Tags and 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 7. #### 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/3a4dc278d1316e9a5a3719c2fb93c942ef8ef6da)Figure 7 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 | | ![](/files/6f2cd236bb1da91339233cfbe41ba923ab087003) |

Thank you! We are the payments architects who
truly understand commerce. As payment architects we shape ecosystems for online and in-person commerce experiences, including all the tools you need… from gateways and acquiring to fraud management, tokenization and reporting. As commerce experts, we are here for you and your business. With our payment devices, our systems & solutions and our support. Everywhere. Anytime. So that your customers feel enabled, recognized and well taken care of, even beyond their expectations. Verifone. Creating omni-commerce solutions that simply shape powerful customer experiences.

| | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | Verifone North America Development The Royal Center Four 11700 Great Oaks Way, Suite 210 Alpharetta, GA 30022 [www.verifone.com](http://www.verifone.com) --- # 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/newtemp_xpi_mobile_wallet_apple_vas2.0_setupguide1.2.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.