SoftPOS - MobilePOS reconciliation

Overview

The Nexi SoftPOS and MobilePOS ecosystem provides multiple methods to retrieve and verify transaction data, depending on the integration model and platform. Below is an overview of the key transaction-retrieval mechanisms available across App2App (Android) and SDK (iOS) integrations.

1. Last Transaction (Android – App2App)

Documentation User-Authentication: https://developer.nexigroup.com/softposmobilepos/en-EU/docs/last-transaction-status/

Documentation Cloud-Authentication: https://developer.nexigroup.com/softposmobilepos/en-EU/docs/get-last-transaction/

This method retrieves details of the last transaction processed by the NexiPOS app. It is typically used by merchant applications integrated via App2App to confirm or display the outcome of the last operation.

Key Points:

• Returns information about the most recent transaction performed on the device.

• Useful when the merchant app loses context after payment (e.g., due to app closure or network loss)

• The response includes all the details of the receipt (see the specification page for more detail)

2. Get List Transactions (iOS SDK Integration)

Documentation: https://developer.nexigroup.com/softposmobilepos/en-EU/docs/beta-sdk-ios-softpos-only/sdk-overview/#build-technical-specification

This SDK-level method provides access to the list of transactions,it is used by applications integrating the SoftPOS SDK to display or manage transaction history directly within the merchant app.

Key Points:

• Returns a local list of transactions performed via the SDK

• Can be filtered or iterated for reporting, receipts, or customer service use cases

3. Check Transaction (API – Android & iOS)

Documentation: (Check the API CHECK TRANSACTION section)

This backend API allows merchant servers to retrieve the full details of a specific transaction using the terminal ID and an optional caller transaction ID. It can be used regardless of the device type (SoftPOS or MPOS) and is ideal for reconciling transactions at the backend level.

Key Points:

• Requires OAuth2 client credentials and a signed JWT client assertion for authentication.

• Response returns detailed transaction information (see the specifications below for more detail)

• Valid for both Android and iOS ecosystems.

• Enables server-side reconciliation and reporting.

4. Webhook - (Android & iOS)

Documentation: (Check the webhook section)

The webhook notifies the merchant system of the outcome of a payment transaction generated by NEXI. The notification is dispatched by the event-generating server to an endpoint exposed by the merchant.

Key Points:

• Requires OAuth2: bearer token generated by the merchant

• Response returns detailed transaction information (see the specifications below for more detail)

• Valid for both Android and iOS ecosystems.

• Enables server-side reconciliation and reporting.

API CHECK TRANSACTION

This API, provided by Nexi, is designed to retrieve detailed information about a specific transaction within the MobilePOS Core system. The transaction is identified by its terminal code and the caller transaction ID.

Authentication: Obtaining Access API usage requires authentication via the OAuth2 Client Credentials flow. This process provides an access token that must be used in all subsequent API calls.

API Bearer token To request the token, make a POST call to the /softpos/appenrollment/token endpoint with the following credentials:

POST <FQDN>/softpos/appenrollment/token

Content-Type: application/x-www-form-urlencoded

{
  "access_token": "<BE_MERCH_TOKEN>",

  "token_type": "Bearer",

The token has a limited lifespan (e.g., 3600 seconds) and must be renewed upon expiration.

JWKS ENDPOINT

This API is on B2B channel, therefore has to be called from the merchant BE in MTLS through developer certificate. This API represent the endpoint to retrive public key to encrypt the client_assertions requested in the header of the API check transaction

curl --request GET --url <FQDN>/softpos/par/jwks.json

CHECK TRANSACTION API

STG - https://stgb2bsoftpos.nexigroup.com/mpos-core/app/checkTransaction

PROD – https://b2bsoftpos.nexigroup.com/mpos-core/app/checkTransaction

This operation allows you to retrieve details for a specific transaction

Service Details:

• Method: POST

• Summary: Retrieve information about a specific transaction.

• Operation ID: checkTransaction

• Authentication Required: A valid Bearer token must be provided in the Authorization header.

• Tag: App (Endpoints for MobilePOS App integration)

Request Header

Request Body (CheckTransactionRequest)

The request must be sent in JSON format and requires the terminalId

Client Assertion

<CLIENT_ASSERTION> is a JWE (cfr. RFC 7516), sign with developer certificate and then encrypted with the key Endpoint JWKS. The plaintext of the <CLIENT_ASSERTION> should be:

{ 

"appId": "<APP_ID>",

"terminal_ids" will have a list of di 1 o 2 TID depending if the merchant purchased one SoftPOS and one MPOS a "iss", "sub", "aud", "iat", "exp" e "jti" are claim standard defined here RFC 7519. "aud": "<SOFTPOS_B2B>" represent the FQDN B2B where the operation has to be performed (stg or prod), <APP_ID> is the Client ID retrived from the web portal configuration. Username_merchant has to be an e-mail format, unique for single TID

API RESPONSE STATUS CODE

{

  "terminalId": "12345678",

<details>
  <summary><strong>Example Response — 200 OK (CheckTransactionResponse)</strong></summary>

```json

Response Schemas

StandardResponse

(Used for general error responses: 401, 404, 500)

FieldErrorDTO

(Used within ValidationErrorDTO)

ValidationErrorDTO

(Used for 400 Bad Request when validation fails)

{
  "statusCode": "401",
  "message": "Unauthorized — invalid or expired token"
}

WEBHOOK

Webhook — Technical Documentation

Purpose

This document describes the webhook used by NEXI to notify the merchant system of the outcome of a payment transaction.

The notification is sent by the NEXI server that generates the event to a publicly exposed endpoint provided by the merchant.

The integration uses a server-to-server communication model based on HTTPS POST requests and OAuth 2.0 bearer token authentication.

Architectural Context

The integration flow consists of a server-to-server communication between NEXI and the merchant backend.

Before invoking the webhook, NEXI authenticates via a dedicated OAuth 2.0 token endpoint exposed by the merchant backend.

Once the webhook request is received, the merchant backend must return a status code reflecting the result of the validation and application-level processing.

Webhook Endpoint

The webhook endpoint URL is defined by the merchant and must be publicly accessible to receive notifications from NEXI.

The endpoint must be registered and appropriately configured before the integration is moved to production by NEXI security team

For endpoint registration and configuration requirements, developers should contact supporto.development@nexigroup.com (All the requests sent without a commercial agreement will be rejected)

Endpoint Requirements

Protocol HTTPS

Visibility Publicly accessible endpoint reachable by NEXI servers

Traffic direction Inbound traffic to the merchant; the endpoint must be registered in the outbound file according to the required process

method POST

Authentication OAuth 2.0 bearer token

OAuth 2.0 Authentication

The merchant must expose a dedicated endpoint for issuing the OAuth 2.0 bearer token required to authenticate requests sent by NEXI.

NEXI must obtain a valid access token before invoking the payment outcome webhook and include the token in the Authorization header of subsequent webhook requests.

Token Endpoint

The token endpoint is exposed by the merchant backend and is used by NEXI to obtain an OAuth 2.0 bearer token.

Property Value

Purpose Issue a bearer token for webhook authentication

Protocol HTTPS

method POST

Webhook Request

Request Headers

In addition to standard HTTP headers, the request must include an OAuth 2.0 bearer token issued by the merchant backend.

The request body is a JSON object containing the following fields:

Example Request POST /merchant/api/payment/webhook HTTP/1.1 Host: merchant.example.com Authorization: Bearer <access_token> Content-Type: application/json

{

"terminalId": "02546095",

"transactionId": "619115023372",

"callerTrxId": "722537285828",

"amount": "500",

"totalAmount": "550",

"scheme": "Debit Mastercard",

"pan": "xxxxxxxxxxxx7149",

"requestDate": "10/07/2026",

"eventDate": "10/07/2026",

"status": "OK",

"tipAmount": "50"

}

Merchant Response

After receiving the webhook POST request, the merchant server must return a status code indicating whether the notification was successfully accepted and processed or whether an error occurred.

The response must also contain a JSON body with a descriptive message.

Response Body { "message": "string" }

Response Codes

The webhook integration must comply with the following security requirements:

• The webhook endpoint must be exposed exclusively over HTTPS.
• Access to the webhook must be protected using OAuth 2.0 bearer token authentication.
• The merchant must expose a dedicated token endpoint for NEXI.
• Failure to validate the bearer token must result in HTTP 401 Unauthorized.
• All received requests should be logged for operational and troubleshooting purposes, including relevant identifiers, timestamps, validation results, and the response code returned.

Operational Flow

The complete payment notification flow is as follows:

1. NEXI requests an access token from the OAuth 2.0 token endpoint exposed by the merchant.
2. The merchant backend authenticates NEXI according to the agreed OAuth 2.0 profile and issues an access token.
3. NEXI generates the payment event.
4. NEXI sends a POST request to the merchant's public webhook endpoint, including the bearer token in the Authorization header.
5. The merchant validates the request, including the access token, payload, and application-level transaction correlation.
6. The merchant updates the internal transaction status associated with callerTrxId.
7. The merchant returns the appropriate HTTP status code together with a JSON response body containing the processing outcome.

The merchant is responsible for exposing, securing, and registering both endpoints before the integration is enabled in production.