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, such as amount, date/time, and result code

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, including status, card type, amount, acquirer ID, and timestamps.

• 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"
}