Local Connect

Discovery protocol

While it is possible to directly connect to the terminal, Local Connect gives you the possibility to discover any PAY.POS terminals on your local network. This is done by sending a UDP message on the broadcast ip address.

IP address: 255.255.255.255
Port: 8889
Message (UTF-8 encoded): PAY.POS-WHO.IS

PAY.POS-I.AM:TH-XXXX-XXXX:TERMINAL NAME

Example code

Connect to PAY.POS

Before you can send messages to the terminal, you need to make sure you are connected via the TCP protocol. PAY.POS is reachable on port 8888

Ping terminal

To make sure you are connected to the terminal and fetch the latest status of the terminal, you can send a PING message:

{
  "type": "PING",
}

{
  "type": "PONG",
  "status": "" // possible values: BOOTING, BUSY, IDLE, ORDER_PRESENTING
}

Error message

It is possible to receive error messages from the terminal. Be prepared for them!

{
  "type": "ERROR",
  "reason": "" // Error message, might contain exception or message validation error
}

Starting a payment

After connecting to the terminal, you will be able to send payment requests to the terminal. The payment request message is based on the Order:Create API. All properties available on the Order:Create is available for the request:

{
  "type": "TRANSACTION_START",
  "transaction": {}, // Check Order:Create api for more details
  "service" { "serviceId": "SL-XXXX-XXXX", "secret": "SECRET" } // Optional, allow service injection
}

Events during the payment

After sending the payment request, you will receive payment event during the transaction. NOTE: Make sure you stay connected during the payment.

Event	Description	Extra information
`STARTED`	Confirmation that the request has been received and terminal is waiting for card	N/A
`PROCESSING`	Notification that terminal has read the card and is authorizing payment	N/A
`COMPLETED`	The payment has completed, can either be approved or declined	Approved Message
`FAILED`	The terminal has failed to read/process payment. Reason can be found in the message property	Message
`CANCELLED`	The payment has been cancelled by user or TRANSACTION_STOP message
`QUEUED`	The payment could not be processed right now, but has been stored to be processed later. Current status of the payment can be requested via HISTORY_GET
`PIN_INPUT_PENDING`	Terminal is waiting for Pincode from customer
`PIN_INPUT_ERROR`	Payment has failed, something went wrong during PIN_INPUT

{
  "type": "TRANSACTION_EVENT",
  "event": "",
  "approved": false,
  "message": ""
}

Stop/cancel a payment

To stop a running payment, send the following message to the terminal:

{
  "type": "TRANSACTION_STOP",
}

History

Local connect allows you to request the current history data of the terminal. You can request a summarized history list or a detailed history item.

📘
Be aware of the payment limit
You can only request the last 20 payments. If you wish to request more, consider using the TGU

List history

{
  "type": "HISTORY_LIST"
}

{
  "type": "HISTORY_LIST_RESPONSE",
  "items": [
    {
      "id": "MV-XXXX-XXXX-XXXX", // Can be null if payment does not have status SUCCESS
      "orderId": "", // Can be null if payment does not have status SUCCESS
      "reference": "", // Only available if provided
      "status": "", // Possible values: SUCCESS (approved), CANCEL, FAILED (declined), EXPIRED, QUEUED
      "createdAt": "2025-07-01T12:59:59.999Z" // ISO8601 format
    }
  ]
}

Get history

{
  "type": "HISTORY_GET",
  "needle": "" // This is either the id, orderId, or reference
}

{
  "type": "HISTORY_GET_RESPONSE",
  "id": "MV-XXXX-XXXX-XXXX", // Can be null if payment does not have status SUCCESS
  "orderId": "", // Can be null if payment does not have status SUCCESS
  "reference": "", // Only available if provided
  "status": "", // Possible values: SUCCESS (approved), CANCEL, FAILED (declined), EXPIRED, QUEUED
  "description": "", // Only available if provided
  "createdAt": "2025-07-01T12:59:59.999Z", // ISO8601 format
  "ticket": "", // Base64 string of ticket or null if payment does not have status SUCCESS
  "amount": 0,
  "currency": "EUR",
  "cardNumber": "1234***1234" // A masked version of the cardnumber
}

Order Presentation

As an alternative payment flow, Local connect allows you to show the order before prompting the customer for a payment. This allows you to use the terminal as an secondary, customer-facing screen.

Start order presentation

To start the Order presentation, you can send the same message for starting a payment to the terminal, but include the different message type

{
  "type": "ORDER_CREATE", // Or use ORDER_UPDATE to update the content of the screen
  "transaction": {}, // Check Order:Create api for more details
  "service" { "serviceId": "SL-XXXX-XXXX", "secret": "SECRET" } // Optional, allow service injection
}

The total amount of the order will be sent by the amount.value property of the message. The terminal does not calculate the total amount. You are responsible for sending the correct total amount.

Only the transaction.order.products, transaction.description, transaction.reference, and transaction.amount will be shown on the screen.

Start the payment

In order to transition from Order presentation to a payment, send the following message to the terminal

{
  "type": "ORDER_START"
}

Stop the order presentation

If you wish to stop presenting the order or start a new one, make sure to send the following to the terminal

{
  "type": "ORDER_STOP"
}