Overview
The Virtual Pin Pad (VPP) can be used for testing the Customer-Present Cloud API without a device. This should be used for testing when a test cloud device is unavailable as the staging platform requires the use of a staging cloud device.
The information below will provide examples of how to register and perform transactions via the VPP. Further documentation for Customer Present Cloud and the VPP may be found within the Integration Portal, found by logging into the Merchant Gateway Account > Selecting Help > Selecting Integration Portal.
Register the VPP
VPP registration requests follow the same format as registering a physical payment device via API requests. In order to register the VPP integrations will need to submit API requests to the Device Management API using the following parameters:
Parameter | Type | Required | Description |
registrationCode | string | yes | The value that appears on an internet-connected device when it is not yet registered or has been deregistered. |
deviceNickname | string | no | When sent will appear on the POI Device screen and in the UI License Manager, as well as in Estate Management queries. |
Registration codes are normally found on the physical payment devices, however, for the VPP you may find the appropriate registration code within the integration portal under the VPP Testing Information section.
Once the registration code has been obtained you will need to submit a request to the device registration endpoint. Here is an example of the parameters to submit to the API endpoint:
POST /api/v2/devices/register
PARAMS: [
security_key : your_security_key
registrationCode : T00001
deviceNickename : "optional parameter to name device"
]
All GUIDs returned associated with the VPP (including POI Device IDs) will always end in 12 zeroes. This will be an indicator that the transaction is a ‘test’ transaction since this will never occur in a live environment.
For example: 3915af04-29fa-49df-88d0-000000000000
Registration requests using T00001 will return a virtual (fake) POI Device ID which can be used to process test payments and will appear in estate management polling requests. This POI Device ID can also be used to simulate deregistration of an EMV terminal.
Performing Test Transactions with the VPP
Once the VPP has been registered and the poi_device_id
has been obtained from the API response you will now be able to perform transactions with the VPP. Customer-Present Cloud transaction requests follow an identical structure to the Payment API with the caveat of needing to include the poi_device_id
parameter in order to communicate the device which will be completing the transaction.
The endpoint to be used for these transactions may be found within the integration portal under the Customer-Present Cloud section under Transaction Processing Options. Here is an example of the parameters for a simple 1.00 transaction which should be posted to the API endpoint:
POST /api/transact.php
PARAMS: [
security_key : your_security_key
poi_device_id : "The registered terminal ID returned at the time of device registration"
type : sale
amount : 1.00
]
**Note: The VPP has no interface, once the request has been submitted the API will complete the transaction and return a simulated response showing that the transaction was completed via a Payment device. When processing with the VPP transactions will also complete instantaneously as no further prompts or actions will be needed, unlike when utilizing a physical device which may ask for confirmation, signature or Zip Code.
Deregister the VPP
Once testing with the VPP has been completed and you no longer need the VPP, best practice would be to deregister the device. In order to deregister the device you will need to call to the Device Estate Management API deregistration endpoint which may be found within the Device Management section of the Customer-Present Cloud documentation.
To deregister the device you will need to perform an API request and include the poi_device_id
to point to the device you would like to deregister. Here is an example of the parameters you should submit to the API endpoint to deregister the VPP:
POST /api/v2/devices/deregister
PARAMS: [
security_key : your_security_key
poi_device_id : "The registered terminal ID returned at the time of device registration"
]
The above request will deregister the device associated with the provide poi_device_id
(the VPP).