Terminal Application

Unifying your payments stack across every channel.

With the advent of portable internet-connected devices, the standardization of operating systems (e.g. Android), payment processing protocols (e.g. Nexo), and contactless payment acceptance (e.g. EMV Contacless), the next generation of payment terminals set out to turn the world of retail payments into a convenient, straightforward operation.

The Switch Terminal Application splits the typical communication flow into two steps. Firstly, the payment data is locally encrypted and sent to the cloud, which will then be routed to any given acquirer processor. This allows you to leverage the Switch Platform, for a true omnichannel experience. Besides, it is fully agnostic, meaning you can choose which terminal vendors, acquirers, and acquirer processors you want to work with. With the Switch Terminal Application, you can have full control over your terminal operations and set up payment in-store through a user-friendly, future proof system.

Terminal Specifications

When using Switch’s Terminal Application you will encounter specific terms which we address in the following table.

ConceptDescription
IDThis is a string of numbers and letters that identifies different Elements of your Terminal, or the Terminal in use itself.
DeviceReferences to Device in your Terminal usually relate to that same device, the payment Terminal you are using.
Manual InsertYou can use the Manual Insert Option to allow your Customers to manually insert their card details (card number, expiration date, CVC).
QR CodeYou can provide your Customers with a QR Code when they intend to pay using mobile applications.
ReceiptYou can provide your Customers with printed receipts or digital versions of these files.
RedirectDepending on the Alternative Payment Methods you make available in the Terminal application, you might employ Redirect to push the Customer to use external applications/devices to proceed with Payment (e.g. Alipay, PayPal).
SessionA Terminal Session represents the time frame you set for every day of Transactions in your store. The transactional data is compiled by Session and you are able to set the time of when Session should end in your Terminal.
Supervisor CodeYour supervisor code is the 6-digit code needed to authorize certain operations in your Terminal. During your Terminal's setup you will be asked to create your supervisor code, to do this simply enter, and re-enter, your chosen 6-digit code when prompted and confirm.
TransactionThe concept of Transaction within the Switch Platform includes Charges, Instruments, and Payments. It represents any Element that requires communication with a Provider. This means that the Transactions listed in your Terminal Application l include more elements beyond successful Payments. For example, they can include unsuccessful Payments, and Refunds.

Terminal Setup

Redirect your Customers to our Hosted Checkout.

Alternative Payment Methods are supported by the Switch Hosted Checkout page. Learn more about Hosted Checkout and contact our Support Team to enable it.

Our Merchant and Terminal APIs allow you to automatically manage and onboard merchants, and also set up accounts and channels, providing the perfect infrastructure to manage your entire terminal fleet.

When setting up your terminal operation it is important to know how to add and make changes to terminals by tapping into your device’s details and settings.

Multiple payment methods are made available through our Terminal Application and supported by the Switch Hosted Checkout, a solution that is sure to make your customers’ lives easier.

Add Terminal

Interested in using the Switch Dashboard?

Contact our Support Team for instructions on how to enable this feature.

Terminals can be created using the Switch Dashboard or following the path described in the instructions below. You can use POST for creating new terminals, apply PATCH to make changes to existing terminals and DELETE outdated terminals.

When creating a Terminal there is some required information which you should keep in mind to configure settings effectively.

Required ParameterDescription
Terminal ModelThis is the model of your terminal device.
Authorization GroupYou can segment your devices by authorization groups of users, meaning that only a specific group of users has permission to access the device. To know more about setting up authorization groups head over to Merchant.
Processing Public KeyThe Processing Public Key is used when establishing communication with Switch.
Serial NumberThis is the Software Serial Number of your terminal device.
Key Serial Number (KSN)This is the encryption key which in combination with the terminal id allows for the description of PIN and PAN numbers.
LanguageThis is the operating language of your device. Currently, the languages available are Portuguese (PT) and English (US).
Supervisor PINThe user who is going to be operating the device should have a Supervisor PIN. This PIN grants permission to perform the day-to-day Terminal operations.
Maintenance PINThe Maintenance PIN is used to grant access to the more technical settings of the device, this includes changing the time/date, or resetting the Terminal.
Session End TimeThe Session End Time is set by you and refers to the time when a cycle of transactions in the Terminal comes to a close. It is commonly set for the time your store would close for the day.

Mind the Software Serial Number.

Most terminal devices come with two different Serial Numbers: the Hardware Serial Number and the Software Serial Number. The Hardware Serial Number can be found on the back of the device.

In the operations set with Switch, the one you need is the Software Serial Number. This one can be found in the device’s system panel application.

POST /v1/terminals

MethodPathDescription
POSTSandbox
https://merchant-api-test.switchpayments.com/v1/terminals

Production
https://merchant-api.switchpayments.com/v1/terminals
Add a new Terminal device to the application.
Request Body Parameters

terminal_modelStringRequired

This is the model of your terminal device.


authorization_group_idStringRequired

Authorization group associated with this device.


processing_public_keyStringRequired

The Processing Public Key is used when establishing communication with Switch.


ksnStringRequired

Key Serial Number for the device.


languageStringRequired

Language applied to this Terminal.


supervisor_pinNumberRequired

The user who is going to be operating the device should have a Supervisor PIN. This PIN grants permission to the user to perform day-to-day Terminal operations.


maintenance_pinNumberRequired

The Maintenance PIN is used to grant access to the more technical settings of the device, this includes changing the time/date, or resetting the Terminal.


daily_session_endTimeRequired

End time for the daily Terminal session.


merchant_nameStringRequired

Label of the merchant operating the Terminal.


metadataString

You can register customized parameters under metadata, namely tracking numbers to your devices.

REQUEST
$ curl -vX POST
https://merchant-api-test.switchpayments.com/v1/terminals?merchant_id=accountId -u accountId:MerchantAPIKey
{
"terminal_model": "castles_saturn_1000",
"authorization_group": "bf3350f69a1a1ef50b587d7837b1c9a",
"processing_public_key": "{{PUBLIC-KEY}}",
"ksn": "KSN",
"settings": {
"language": "en",
"supervisor_pin": "1234",
"maintenance_pin": "4321",
"daily_session_end": "12:12",
"merchant_name": "name",
},
"metadata": {
"x": "y"
}
}

Users are able to set customized parameters under metadata. This field might come in handy when you intend to register specific messages for your collaborators or intend to add tracking numbers to your devices. Here are some examples of metadata parameters to clarify its functionality.

ExampleDescription
store: ‘Porto’Physical location of this device, in this case the store it is located in.
section: ‘reception desk’Physical location of this device, in this case the section of the store it is located in.
store-address: ‘Avenida da Boavista, Porto’Physical location of this device, in this case the address of the store it is located in.
current-status: ‘inactive, store on vacation’The status of the device. Whether it is currently operable or not.
merchant-terminal-id: ‘abcde’Specific IDs related to the internal operations of your business.
administrator-name: ‘Maria’Staff identification that might be useful to share with the team.

Response Parameters

idString

This is the identification generated for the Terminal in question.


authorization_group_idString

Authorization group associated with this device.


created_atDate

The date in which the Terminal was created.


ksnString

Key Serial Number for the device.


merchant_idString

Identification of the merchant operating the Terminal.


processing_public_keyString

The Processing Public Key is used when establishing communication with Switch.


daily_session_endTime

Daily end time for the Terminal session.


languageString

Language applied to this Terminal.


maintenance_pinNumber

The Maintenance PIN is used to grant access to the more technical settings of the device, this includes changing the time/date, or resetting the Terminal.


merchant_nameString

Label of the merchant operating the Terminal.


supervisor_pinNumber

The user who is going to be operating the device should have a Supervisor PIN. This PIN grants permission to the user to perform the day-to-day terminal operations.


terminal_modelString

This is the model of your terminal device.


updated_atDate

Date in which the Terminal was last updated.

RESPONSE: HTTP 200
{id: "4971cd5732e4e5e21cf488f61db64d6f7f227fcc5ebe6c15"}
authorization_group_id: "bf3350f69a1a1ef50b587d7837b1"
created_at: "2020-05-15T10:16:53.101636+00:00"
id: "4971cd5732e4e5e21cf488f61db64d6f7f227fcc5ebe6c15"
ksn: KSN
merchant_id: "Lq9aVoz7eI852ID7ffNgGD9rr9Grv3ZQeE9dt"
processing_public_key: "123abc"
settings: {language: "en", merchant_name: "Name", supervisor_pin: "1234", maintenance_pin: "4321"}
daily_session_end: "12:12"
language: "en"
maintenance_pin: "4321"
merchant_name: "Name"
supervisor_pin: "1234"
terminal_model: "castles_saturn_1000"
updated_at: "2020-05-19T18:26:19.210989+00:00"

Terminal Details

When you access the details of a specific Terminal, you should be able to find specific identifiers of your device, the necessary keys to access it and the dates in which it was created or modified.

DesignationDescription
Terminal IDThis is the string of numbers and letters which identifies your Terminal.
Authorization Group IDThis is the identification of the authorization group associated with the device. You can segment your devices by authorization groups of users, meaning that only a specific group of users has permission to access the device.
Processing Public KeyThe Processing Public Key is used when establishing communication with Switch.
Serial NumberThis is the Software Serial Number of your terminal device.
Key Serial Number (KSN)This is the encryption Key which in combination with the Terminal ID allows for the description of PIN and PAN numbers.
Date CreatedThe date in which the Terminal was established.
Date Last UpdatedThe date in which the Terminal was last updated.

Mind the Software Serial Number.

Most terminal devices come with two different Serial Numbers: the Hardware Serial Number and the Software Serial Number. The Hardware Serial Number can be found on the back of the device.

In the operations set with Switch, the one you need is the Software Serial Number. This one can be found in the device’s system panel application.

Terminal Settings

Terminal Settings have to do with how you operate your device. These concern your customer’s and collaborator’s user experience with the Terminal, how they identify your device, the payment methods they can employ and the ways in which they handle and retrieve information.

DesignationDescription
LanguageThis is the operating language of your device. Currently, the languages available are Portuguese (PT) and English (US).
Merchant NameThis is the name of the merchant, meaning brand or business, operating the device.
Supervisor PINThe user who is going to be operating the device should have a Supervisor PIN. This PIN grants permission to the user to perform the day-to-day Terminal operations.
Maintenance PINThe Maintenance PIN is used to grant access to the more technical settings of the device, this includes changing the time/date, or resetting the Terminal.
Daily Session End TimeThe Session End Time is set by you and refers to the time when a cycle of transactions in Terminal comes to a close. It is commonly set for the time your store would close for the day.
EMV Reader EnabledYou can enable or disable the EMV Reader capabilities of your device. EMV is a global standard for credit cards that use computer chips to authenticate and secure chip card transactions.
Contactless Reader EnabledYou can enable or disable the Contactless Reader capabilities of your device. Contactless smart card readers use radio waves to read and write data on a smart card.
Magnetic Stripe Reader EnabledYou can enable or disable the Magnetic Stripe Reader capabilities of your device. A magnetic stripe reader reads the information encoded in the magnetic stripe of cards.

Search Terminal

You are able to find Terminal Details and Settings by going over your list of Terminals in the Switch Dashboard or by employing a GET call to our Merchant API using the Terminal ID, as follows.

GET /v1/terminals{id}

MethodPathDescription
GETSandbox
https://merchant-api-test.switchpayments.com/v1/terminals{id}

Production
https://merchant-api.switchpayments.com/v1/terminals{id}
Get Terminal details and settings.
REQUEST
$ curl -vX POST
https://merchant-api-test.switchpayments.com/v1/terminals{id}?merchant_id=accountId -u accountId:MerchantAPIKey
Response Parameters

idString

This is the identification generated for the Terminal in question.


authorization_group_idString

Authorization group associated with this device.


created_atDate

The date in which the Terminal was created.


ksnString

Key Serial Number for the device.


merchant_idString

Identification of the merchant operating the Terminal.


processing_public_keyString

The Processing Public Key is used when establishing communication with Switch.


daily_session_endTime

Daily end time for the Terminal session.


languageString

Language applied to this Terminal.


maintenance_pinNumber

The Maintenance PIN is used to grant access to the more technical settings of the device, this includes changing the time/date, or resetting the Terminal.


merchant_nameString

Label of the merchant operating the Terminal.


supervisor_pinNumber

The user who is going to be operating the device should have a Supervisor PIN. This PIN grants permission to the user to perform the day-to-day terminal operations.


terminal_modelString

This is the model of your terminal device.


updated_atDate

Date in which the Terminal was last updated.

RESPONSE: HTTP 201
{id: "4971cd5732e4e5e21cf488f61db64d6f7f227fcc5ebe6c15"}
authorization_group_id: "bf3350f69a1a1ef50b587d7837b1c9a130a56f"
created_at: "2020-05-15T10:16:53.101636+00:00"
id: "4971cd5732e4e5e21cf488f61db64d6f7f227fcc5ebe6c15"
ksn: KSN
merchant_id: "Lq9aVoz7eI852ID7ffNgGD9rr9Grv3ZQeE9dtfF0KvE6QxGQLwmjCPFkqmpP6td"
processing_public_key: "123abc"
settings: {language: "en", merchant_name: "Name", supervisor_pin: "1234", maintenance_pin: "4321"}
daily_session_end: "12:12"
language: "en"
maintenance_pin: "4321"
merchant_name: "Name"
supervisor_pin: "1234"
terminal_model: "castles_saturn_1000"
updated_at: "2020-05-19T18:26:19.210989+00:00"

Looking to share this User Guide with your collaborators?

Access the Switch Terminal User Guide which includes Terminal Specifications for easy sharing.

Terminal User Guide

The workflow in the Switch Terminal Application was designed to be user-friendly, simple, and future-proof.

Most operations you are able to execute when using the Terminal Application are linear and produce clear results, making the interaction simple and straightforward. You have access to multiple tools to help you search transactions and the details of your operation so that you can always keep an eye on your store’s performance.

Supervisor

Under the Supervisor section, you can find your list of transactions and the details of the current session, as previously described. You can also go over the terminal details, disable the device, and change the default language. Supervisor Terminal options can only be accessed with a Supervisor PIN, the prompt to input this PIN will appear upon selection.

Maintenance

Maintenance includes the more technical details of the Terminal management, apart from the day to day operations available to supervisors. This includes making changes to the date/time of the device and resetting the Terminal completely.

Sessions

Terminal sessions can either be enabled manually, or scheduled in advance. You can check each session’s performance, with amounts processed, the number of transactions, refunds, and declines.

Terminal Details

In Terminal Details, you can get an overview of the features and current state of your device. This includes the Terminal ID, the environment of your operations, keys, and details on your Terminal and Terminal Application version.

Payments

  1. Input amount using the Terminal screen. In the Terminal, a calculator is available to ease cash payments.
  2. Consumers can choose whether they would like to add a tip to the original price or not, just use the Add Tip option. Tips can be calculated by a percentage of the amount to be paid or you can input a specific value.
  3. Consumers can choose how they want to pay. They can make use of their card as usual, or proceed with the alternative payment methods you decide to remotely deploy to the POS (e.g. PayPal, Alipay). When using alternative payment methods, the user interface will display a QR code that customers can scan using their mobile devices. This will redirect them to a checkout page where they can proceed with the payment.
  4. After each payment, consumers can choose between a printed or digital receipt.

Transactions and Refunds

All transactions are listed on the Switch Dashboard, but you also have access to the ones processed during the current session right on the Terminal Application.

  1. To search transactions, you can use the QR code on each receipt or any other detail about the transaction. This includes the timeframe in which the transaction was handled and the payment instrument used. Everything is searchable and all data is available in real-time.
  2. To proceed with refunds, simply find the transaction you would like to refund and establish the refund amount, you can create partial or total refunds.

Next Steps

Would you like to know more about the Switch interface? Get to know our Dashboard Application and all the features you can manage with it.