Documentazione
Documentazione
terminale

1Terminal APIs

In general there are three APIs how you can interact with the terminal via API:

Cloud Till Interface: By using the cloud interface you are using a public reachable API to interact with the terminal device. The benefit is you do not need to know where the device is located and it works from any network. However there is a higher delay compared to other integration methods because the communication happens via a central server. The Cloud Till Interface documentation can be found below.

Local Till Interface: By using the local till interface you connect directly with a socket to the terminal device. The benefit is that you have a fast connection as both your application and the terminal device are in the same local network. The drawback is that you need to know the terminal's IP address. The Local Till Interface documentation changes depending on the application version installed on the terminal device.

Android Till Interface: By using the Android till interface you can directly talk to the terminal software. The benefit is that you can use an Android SDK to interact with the terminal but you can do that only for applications that will run on the terminal. If the application is not running on the terminal the Android till interface does not work. For the Android Till Interface you will need to add the SDK to your Android app as a dependency.

For testing and publication of your Android app please get in contact with us.

2Different Cloud Till Interfaces

Generally there are are two ways to process payments on a terminal:

  • Use the terminal in the standalone mode where the cashier is entering the amount to charge on the terminal or

  • connect the till to the terminal and allow the till to coordinate the payment on the terminal.

In the standalone mode there is no integration required and as such it can be simply used. The transactions done on the terminal will appear in the transaction list once they are executed.

If you plan to integrate your application with the terminal you have the following options:

  • Connect to the terminal through a socket in the local network. If you are looking for this integration please get in contact with us.

  • Connect to the terminal through a websocket. The WebSocket will use a server from our side to connect to the terminal device.

  • Connect to the terminal through a long polling HTTP request.

The rest of the documentation focus on the two later connection methods. The connection methods are in general very similar:

  1. Ensure the terminal is connected to the Internet. This might be different depending on the terminal hardware.

  2. Create a transaction with the Transaction Service. Use the create operation to create a new transaction.

  3. Connect your till to initialize the processing of the payment by using WebSockets or the long polling mechanism.

The creation of the transaction is done in the same way as for any other integration.

When you are not sure which method to use we have tried to list some properties of the different methods:

  • Long polling is simpler to integrate as the WebSockets long polling uses just a standard web service operation.

  • Long polling does not offer any interaction with the attendee. Those interactions allow a better experience for the attendee.

3Till Integration with Long Polling

As a first step you have to create a transaction. For this you can use the Transaction Service and the create operation.

Afterwards you can use the perform transaction operation to trigger on the terminal a transaction. The perform transaction operation does not answer the HTTP response for around at maximal 80 seconds. During that time the terminal tries to carry out the transaction. When the transaction succeeds or fails the perform transaction operation will return the result immediately. In case the terminal needs more time the method will respond with the HTTP status 543. In this case the method has to be invoked again with the same parameters.

The following pseudo code shows how to implement the pattern:

function carryOutTransaction(spaceId, terminalId, transactionId) {
	for (i = 0; i < 10; i++) {
		try {
			paymentTerminalTillService.performTransaction(spaceId, transactionId, terminalId);
		}
		catch(Exception e) {
			// We log the exception but do not stop the processing. Generally
			// it is better not just to repeat with the status code 543 rather also
			// with any other error that can be caused by a connection issue.
			log(e);
		}
	}
}

There are two different perform transaction operations on the Payment Terminal Till Service:

  • You can perform the transaction with the terminal ID or

  • You can perform the transaction with the terminal identifier.

The terminal identifier is the ID that you see also on the receipt etc. The pattern is 3xxx xxxx. Where as the terminal identifier is a shorter number only visible with in the portal.

4Till Integration with WebSockets

As there are interactions between the cashier and the terminal during the payment process a technique has to be used which supports this. Specifically the interaction requires a two way communication. WebSockets allow this kind of communication.

Within the WebSocket the STOMP protocol is used to exchange messages. See https://stomp.github.io/stomp-specification-1.2.html

4.1Connect

The connect will open the connection and as a result the transaction processing on the terminal will start. All the details about the transaction like amount etc. is taken from the transaction object as created earlier with the Transaction Service over the regular REST API.

When the WebSocket is breaking because of a network issue (e.g. in a mobile network this can happen often) the payment processing will not stop. The WebSocket can be again opened and the Connect can be sent again. The transaction is tried to be resumed. If the timeout has been reached the transaction will fail and accordingly the error message will be sent from the server. In this case a new transaction must be started.

4.2WebSocket Messages

The messages to display on the till are passed as plain JavaScript objects and can contain the following elements.

4.2.1Notification

The notification contains information to display to the attendant on the till.

{
	information: {
		elements: [ ... ],
		recipient: "CUSTOMER" or "MERCHANT"
	}
}

4.2.2Question

The question contains information to display to the attendant on the till and options he needs to chose from.

{
	information: {
		elements: [ ... ],
		recipient: "CUSTOMER" or "MERCHANT"
	},
	options: [
		{
			identifier: "option-1",
			text: "First option",
			primary: true
		},
		{
			identifier: "option-2",
			text: "Second option",
			primary: false
		}
	]
}

4.2.3Error

Errors to WebSocket requests contain the following information.

{
	id: "ab-1234567 (2000-01-01T00:00:00.000Z)",
	date: "2000-01-01T00:00:00.000",
	message: "Translated error message",
	defaultMessage: "English error message",
	type: "END_USER_ERROR" or "CONFIGURATION_ERROR" or "DEVELOPER_ERROR" or "SERVER_ERROR"
}

4.3Elements

Paragraph

The paragraph represents a block of text.

Example

Ridiculus metus pulvinar morbi natoque sem etiam dictum, hac ipsum placerat risus orci est ante, fames tellus felis erat elit gravida. Euismod facilisis gravida sollicitudin nisi pellentesque tincidunt enim fusce dictum sit, odio magna feugiat interdum varius himenaeos diam venenatis sociis.

{
	text: "Ridiculus metus pulvinar morbi natoque sem etiam dictum, hac ipsum placerat risus orci est ante, fames tellus felis erat elit gravida. Euismod facilisis gravida sollicitudin nisi pellentesque tincidunt enim fusce dictum sit, odio magna feugiat interdum varius himenaeos diam venenatis sociis.",
	type: "PARAGRAPH"
}

Ordered List

The ordered list represents a numbered list of items:

Example

  1. First

  2. Second

  3. Third

{
	items: [
		{ text: "First" },
		{ text: "Second" },
		{ text: "Third" }
	],
	type: "ORDERED_LIST"
}

Unordered List

The unordered list represents a list of items with bullet points.

Example

  • First

  • Second

  • Third

{
	items: [
		{ text: "First" },
		{ text: "Second" },
		{ text: "Third" }
	],
	type: "UNORDERED_LIST"
}

Description List

The ordered list represents a list of items with description.

Example
First

The first element

Second

The second element

Third

The third element

{
	items: [
		{
			description: "First",
			text: "The first element"
		},
		{
			description: "Second",
			text: "The second element"
		},
		{
			description: "Third",
			text: "The third element"
		}
	],
	type: "DESCRIPTION_LIST"
}

Table

Table 1. Example
Text Number Amount

First

1

USD1.00

Second

2

CHF2.00

Third

3

EUR3.00

 
{
	columns: [
		{
			identifier: "text",
			text: "Text",
			type: "TEXT"
		},
		{
			identifier: "number",
			text: "Number",
			type: "NUMBER"
		},
		{
			identifier: "amount",
			text: "Amount",
			type: "AMOUNT"
		}
	],
	rows: [
		{ cells: [
			{ column: "text", text: "First" },
			{ column: "number", text: "1" },
			{ column: "amount", text: "USD1.00" }
		] },
		{ cells: [
			{ column: "text", text: "Second" },
			{ column: "number", text: "2" },
			{ column: "amount", text: "CHF2.00" }
		] },
		{ cells: [
			{ column: "text", text: "Third" },
			{ column: "number", text: "3" },
			{ column: "amount", text: "EUR3.00" }
		] },
	],
	type: "TABLE"
}

5JavaScript SDK

To connect your till via a WebSocket using JavaScript, we recommend using our TerminalTillConnection JavaScript utility.

  1. Include the JavaScript file of the utility.

    <script src="https://checkout.postfinance.ch/assets/payment/terminal-till-connection.js" type="text/javascript"></script>

  2. Create a new instance of TerminalTillConnection passing the WebSocket URL, the connection credentials as options.

    var tillConnection = new TerminalTillConnection({
	url: "wss://checkout.postfinance.ch/terminal-websocket",
	token: "[connection-credentials]"
});

  3. Subscribe to events to handle messages from the terminal.

    tillConnection.subscribe("notification", function(payload){
	// Display the information on the till.
});

tillConnection.subscribe("question", function(payload, callback){
	// Display the question on the till and allow the attendant to chose one of the options.
	// Call the callback method with the chosen option's identifier as argument.
	callback(optionIdentifier);
});

tillConnection.subscribe("charged", function(){
	// The transaction has been successfully charged.
});

tillConnection.subscribe("canceled", function(){
	// The payment was canceled.
});

tillConnection.subscribe("error", function(error){
	// An error occurred during the process of a WebSocket request.
});

tillConnection.subscribe("connected", function(){
	// The connection has been established.
});

tillConnection.subscribe("disconnected", function(){
	// The connection has been disconnected or lost.
});

  4. Establish the connection.

    tillConnection.connect();

  5. Use the cancel method to cancel the payment.

    tillConnection.cancel();