Typical Flows

This page is currently only available in English.

Looking for a simpler integration path?

The Nexi OPI Proxy hides the TCP, XML, callback, and receipt-handling complexity behind a local HTTP and JSON API.

Explore the OPI Proxy

This page focuses on the flows integrators usually care about first. It is not meant to be a complete schema reference. The goal is to show how the most common retail flows map into OPI and what to watch out for when you implement them.

The Flows Most Teams Start With

For most attended retail integrations, the practical starting set is:

  • sale
  • refund
  • receipt reprint
  • terminal info and status
  • reconciliation
  • close day

If your merchant setup needs more, the next typical layer is:

  • preauthorisation
  • capture of a preauthorisation
  • cancellation of a preauthorisation
  • abort
  • activate / deactivate
  • transmission / submit

Sale

A standard sale uses:

  • CardServiceRequest
  • RequestType="CardPayment"

Minimal sale request

<?xml version="1.0" encoding="utf-8"?>
<CardServiceRequest WorkstationID="POS-1"
                    RequestID="2001"
                    RequestType="CardPayment"
                    ReferenceNumber="ORDER-2001"
                    xmlns="http://www.nrf-arts.org/IXRetail/namespace">
  <POSdata LanguageCode="en">
    <POSTimeStamp>2026-04-08T10:30:00+02:00</POSTimeStamp>
    <ShiftNumber>1</ShiftNumber>
    <ClerkID>12</ClerkID>
  </POSdata>
  <TotalAmount Currency="CHF">49.90</TotalAmount>
</CardServiceRequest>

Notes

  • DeviceRequest handling is part of the flow
  • receipt output normally comes back through DeviceRequest
  • if tips are enabled, the terminal can return a different final total than the original request
  • if DCC is enabled, the terminal drives the DCC conversation during the payment flow

Preauthorisation

Preauthorisation typically uses:

  • CardServiceRequest
  • RequestType="CardReservation"
<?xml version="1.0" encoding="utf-8"?>
<CardServiceRequest WorkstationID="POS-1"
                    RequestID="2101"
                    RequestType="CardReservation"
                    ReferenceNumber="RES-2101"
                    xmlns="http://www.nrf-arts.org/IXRetail/namespace">
  <POSdata LanguageCode="en">
    <POSTimeStamp>2026-04-08T10:45:00+02:00</POSTimeStamp>
    <ShiftNumber>1</ShiftNumber>
    <ClerkID>12</ClerkID>
  </POSdata>
  <TotalAmount Currency="CHF">150.00</TotalAmount>
</CardServiceRequest>

What to store from the response

If you plan to capture or cancel later, store the response references from the successful reservation, especially:

  • ApprovalCode
  • TrxReferenceNumber
  • the POS-side reference you sent
  • terminal-side identifiers needed by the target profile

Capture After Preauthorisation

In practice, capture is usually implemented as a follow-up CardPayment that references the original reservation.

Typical fields used from the original authorisation:

  • ApprovalCode
  • TrxReferenceNumber
<?xml version="1.0" encoding="utf-8"?>
<CardServiceRequest WorkstationID="POS-1"
                    RequestID="2102"
                    RequestType="CardPayment"
                    xmlns="http://www.nrf-arts.org/IXRetail/namespace">
  <POSdata LanguageCode="en"
           ApprovalCode="123456"
           TrxReferenceNumber="384999238">
    <POSTimeStamp>2026-04-08T11:15:00+02:00</POSTimeStamp>
    <ShiftNumber>1</ShiftNumber>
    <ClerkID>12</ClerkID>
  </POSdata>
  <TotalAmount Currency="CHF">120.00</TotalAmount>
</CardServiceRequest>
  • do not assume ApprovalCode alone is enough everywhere
  • keep the original reservation response data
  • align the exact capture reference model with the target terminal profile

Cancel a Reservation

Cancellation typically uses:

  • CardServiceRequest
  • RequestType="PaymentReversal"
<?xml version="1.0" encoding="utf-8"?>
<CardServiceRequest WorkstationID="POS-1"
                    RequestID="2301"
                    RequestType="PaymentReversal"
                    xmlns="http://www.nrf-arts.org/IXRetail/namespace">
  <POSdata LanguageCode="en"
           ApprovalCode="492321"
           TrxReferenceNumber="384999238">
    <POSTimeStamp>2026-04-08T12:10:00+02:00</POSTimeStamp>
    <ShiftNumber>1</ShiftNumber>
    <ClerkID>99</ClerkID>
  </POSdata>
</CardServiceRequest>

Refund

Refunds typically use:

  • CardServiceRequest
  • RequestType="PaymentRefund"
<?xml version="1.0" encoding="utf-8"?>
<CardServiceRequest WorkstationID="POS-1"
                    RequestID="2201"
                    RequestType="PaymentRefund"
                    ReferenceNumber="REF-2201"
                    xmlns="http://www.nrf-arts.org/IXRetail/namespace">
  <POSdata LanguageCode="en"
           RequestTransactionInformation="true">
    <POSTimeStamp>2026-04-08T12:00:00+02:00</POSTimeStamp>
    <ShiftNumber>1</ShiftNumber>
    <ClerkID>99</ClerkID>
  </POSdata>
  <TotalAmount Currency="CHF">25.00</TotalAmount>
</CardServiceRequest>
  • refund permissions should be enforced by the POS
  • refund availability depends on terminal and merchant configuration
  • receipt handling matters here just as much as on payments

Receipt Reprint

Integrated setups should support reprint.

Typical OPI mapping:

  • CardServiceRequest
  • RequestType="TicketReprint"
<?xml version="1.0" encoding="utf-8"?>
<CardServiceRequest WorkstationID="POS-1"
                    RequestID="2401"
                    RequestType="TicketReprint"
                    xmlns="http://www.nrf-arts.org/IXRetail/namespace">
  <POSdata LanguageCode="en">
    <POSTimeStamp>2026-04-08T12:20:00+02:00</POSTimeStamp>
    <ShiftNumber>1</ShiftNumber>
    <ClerkID>12</ClerkID>
  </POSdata>
</CardServiceRequest>

The terminal will typically resend output through DeviceRequest.

Terminal Info and Status

These are service flows, not card flows.

Common examples:

  • GetInfo
  • GetStatus

These are especially useful during setup, diagnostics, and support.

Reconciliation and Close Day

Typical service flows:

  • Reconciliation
  • CloseDay

Example close-day request:

<?xml version="1.0" encoding="utf-8"?>
<ServiceRequest WorkstationID="POS-1"
                RequestID="2501"
                RequestType="CloseDay"
                xmlns="http://www.nrf-arts.org/IXRetail/namespace">
  <POSdata LanguageCode="en">
    <POSTimeStamp>2026-04-08T23:00:00+02:00</POSTimeStamp>
    <ShiftNumber>1</ShiftNumber>
    <ClerkID>12</ClerkID>
  </POSdata>
</ServiceRequest>

Submit and Transmit

In some merchant setups, transactions are submitted automatically. In others, explicit transmission remains relevant.

Typical mapping:

  • ServiceRequest
  • RequestType="TransmitTrx"

Abort

Abort is useful when a card flow is in progress and the POS needs to interrupt it.

Typical mapping:

  • CardServiceRequest
  • RequestType="AbortRequest"

This does not replace proper unknown-result recovery after transport failure.

Activate and Deactivate

Some setups require explicit terminal login or logout style flows.

Typical service mappings:

  • Login
  • LogOff

Whether these flows are needed depends on terminal behaviour and merchant setup.

Device Interaction Is Part of Every Serious Flow

During many of the flows above, the terminal can send DeviceRequest back to the POS.

Typical reasons:

  • cashier display output
  • receipt printer output
  • e-journal output
  • cashier input

The POS must respond with a matching DeviceResponse.

Example output callback

<?xml version="1.0" encoding="utf-8"?>
<DeviceRequest WorkstationID="POS-1"
               RequestID="2001"
               RequestType="Output"
               SequenceID="1"
               xmlns="http://www.nrf-arts.org/IXRetail/namespace">
  <Output OutDeviceTarget="Printer">
    <TextLine>MERCHANT RECEIPT</TextLine>
    <TextLine>AMOUNT CHF 49.90</TextLine>
  </Output>
</DeviceRequest>

Matching response

<?xml version="1.0" encoding="utf-8"?>
<DeviceResponse WorkstationID="POS-1"
                RequestID="2001"
                RequestType="Output"
                OverallResult="Success"
                xmlns="http://www.nrf-arts.org/IXRetail/namespace">
  <Output OutDeviceTarget="Printer" OutResult="Success" />
</DeviceResponse>

Practical flow advice

  • store references from successful transactions
  • keep RequestID unique
  • treat receipt handling as part of the transaction itself
  • test DCC and tip behaviour only if enabled for the merchant
  • do not assume optional fields are universally supported

If you do not want to handle OPI directly

If you prefer an HTTP and JSON integration instead of TCP and XML, the Nexi OPI Proxy hides these flows behind a simpler local API: OPI Proxy

Zurück
Integration and TCP Communication
Integration
Weiter
Test Cases
Integration