Overview

This guide explains how to integrate a card terminal with Xentral POS to automate credit card payments.

When a credit card payment is triggered in Xentral POS, a webhook with the event type pos.paymentCreditCardCaptured is sent.
The webhook contains all necessary payment data.

📘

Information:

Xentral POS does not communicate directly with the terminal.
A middleware service is required to receive the webhook and forward the payment to the terminal.

Event Flow

🚧

Important Notice:

The structure of the pos.paymentCreditCardCaptured webhook event is currently subject to change.
An updated version of this event is expected in July 2025.
Please use this integration with caution and anticipate potential changes to the payload format.
For implementation guidance or updates, please contact Xentral Support.

Event Trigger: pos.paymentCreditCardCaptured

This webhook is sent when a payment with credit card is selected in the POS.

Payload Example

{
  "operation": "sale",
  "project": {
    "id": "3f942a4b-728c-4c1b-8c7c-3499f28744a1",
    "number": "POS-01"
  },
  "currency": "EUR",
  "amount": 25.90,
  "documentNumber": "40001234",
  "documentType": "invoice",
  "createdAt": "2025-06-11T15:32:00+02:00"
}

Payload fields include:

• amount – The payment amount
• currency – e.g. EUR
• operation – e.g. sale or refund
• project – Optional, to distinguish between multiple registers

For full payload structure, see Webhook Reference.

Middleware Requirements

To integrate the terminal, you need a middleware component that:

1. Receives the webhook from Xentral POS
2. Forwards the payment request to your terminal via API or local interface

The middleware can be built with Node.js (e.g. Express), Python (e.g. Flask), or any other HTTP-capable backend framework.

Example Architecture

Implementation Example (Python Flask)

from flask import Flask, request, jsonify
import requests

app = Flask(__name__)

@app.route('/webhook/pos-payment', methods=['POST'])
def handle_webhook():
    data = request.json
    amount = data.get('amount')
    currency = data.get('currency')
    operation = data.get('operation')
    project = data.get('project')

    terminal_url = "http://192.168.1.100:8080/payment"
    terminal_payload = {
        "amount": amount,
        "currency": currency,
        "type": operation
    }

    try:
        terminal_response = requests.post(terminal_url, json=terminal_payload, timeout=5)
        terminal_response.raise_for_status()
        return jsonify({"status": "success", "terminal_response": terminal_response.json()})
    except requests.exceptions.RequestException as e:
        return jsonify({"status": "error", "message": str(e)}), 500

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

Requirements

• Python 3.x
• Flask and requests libraries
• Accessible terminal IP or network interface

Advanced Example: ZVT-based Terminal Integration

from flask import Flask, request
from ecrterm import ECR

app = Flask(__name__)

@app.route('/webhook/pos-payment', methods=['POST'])
def handle_webhook():
    data = request.json
    amount = data.get('amount')
    currency = data.get('currency')
    operation = data.get('operation')

    terminal = ECR(host='192.168.1.100', port=12345)

    if operation == 'sale':
        response = terminal.sale(amount)
    elif operation == 'refund':
        response = terminal.refund(amount)
    else:
        return 'Invalid operation', 400

    if response.success:
        return 'Payment processed successfully', 200
    else:
        return 'Payment failed', 500

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

Who Can Implement This?

Any developer or technician with basic web development skills:

• Ability to create a REST API
• Knowledge of HTTP, local IP addressing
• Basic understanding of payment systems or terminal APIs

No deep ERP knowledge is required — just the ability to receive data and forward it to a device.