mcp-nexi-pos-api

MVP MCP server for Nexi POS payment operations.

It provides tools to create purchases and refunds, poll payment state, confirm transactions, recover unconfirmed transactions, check terminal status, and list terminal events.

Setup

From npm package

npm install -g mcp-nexi-pos-api
mcp-nexi-pos-api

From source

npm install
npm run build
npm start

Minimum working config

You need Nexi POS API credentials before you can use the server:

• NEXI_POS_API_KEY_ID
• NEXI_POS_API_KEY_SECRET
• a Nexi POS terminal ID

The terminal ID is generated together with the API key ID and API key secret. Credential and terminal generation is outside this MCP server for now. Get these values from Nexi API documentation before starting the server.

The smallest useful .env file is:

NEXI_POS_API_KEY_ID=your-api-key-id
NEXI_POS_API_KEY_SECRET=your-api-key-secret
NEXI_POS_TERMINAL_ID=your-terminal-id

NEXI_POS_TERMINAL_ID is optional. It is used as an environment fallback when a tool call does not include terminal_id and no session terminal has been set with set_terminal_id. It has no default value.

A fuller local .env file can include:

NEXI_POS_API_KEY_ID=your-api-key-id
NEXI_POS_API_KEY_SECRET=your-api-key-secret
NEXI_POS_TERMINAL_ID=your-terminal-id
NEXI_POS_BASE_URL=https://api.sandbox.npay.eu/pos/v1
NEXI_POS_DEFAULT_CURRENCY=SEK
NEXI_POS_MAX_AMOUNT_MINOR=100021
NEXI_POS_USER_AGENT=mcp-nexi-pos-api/0.1.4
NEXI_POS_STORAGE_PATH=./data/nexi-pos.sqlite
NEXI_POS_REQUEST_TIMEOUT_SECONDS=30

Environment variables

| Variable | Description | Default | | --- | --- | --- | | NEXI_POS_API_KEY_ID | Nexi Basic Auth username. Generated outside this MCP server. | Required | | NEXI_POS_API_KEY_SECRET | Nexi Basic Auth password. Generated outside this MCP server. | Required | | NEXI_POS_TERMINAL_ID | Optional terminal ID fallback when no tool terminal_id or session terminal ID is available. Generated with the API credentials. | No default | | NEXI_POS_BASE_URL | Nexi POS API base URL. | https://api.sandbox.npay.eu/pos/v1 | | NEXI_POS_DEFAULT_CURRENCY | Currency used when a tool omits currency. | SEK | | NEXI_POS_MAX_AMOUNT_MINOR | Safety limit in minor units. Defaults high enough for Nexi test-case amounts. | 100021 | | NEXI_POS_USER_AGENT | User agent sent to Nexi. | mcp-nexi-pos-api/0.1.4 | | NEXI_POS_STORAGE_PATH | SQLite file for local recovery state. | ./data/nexi-pos.sqlite | | NEXI_POS_REQUEST_TIMEOUT_SECONDS | Hard timeout for each HTTP request to Nexi. | 30 |

Claude Desktop config

Minimum example for a global npm install:

{
  "mcpServers": {
    "nexi-pos": {
      "command": "mcp-nexi-pos-api",
      "env": {
        "NEXI_POS_API_KEY_ID": "your-api-key-id",
        "NEXI_POS_API_KEY_SECRET": "your-api-key-secret",
        "NEXI_POS_TERMINAL_ID": "your-terminal-id"
      }
    }
  }
}

Fuller example for a global npm install:

{
  "mcpServers": {
    "nexi-pos": {
      "command": "mcp-nexi-pos-api",
      "env": {
        "NEXI_POS_API_KEY_ID": "your-api-key-id",
        "NEXI_POS_API_KEY_SECRET": "your-api-key-secret",
        "NEXI_POS_TERMINAL_ID": "your-terminal-id",
        "NEXI_POS_BASE_URL": "https://api.sandbox.npay.eu/pos/v1",
        "NEXI_POS_DEFAULT_CURRENCY": "SEK",
        "NEXI_POS_MAX_AMOUNT_MINOR": "100021",
        "NEXI_POS_STORAGE_PATH": "/absolute/path/to/data/nexi-pos.sqlite"
      }
    }
  }
}

Example from source:

{
  "mcpServers": {
    "nexi-pos": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-nexi-pos-api/dist/index.js"],
      "env": {
        "NEXI_POS_API_KEY_ID": "your-api-key-id",
        "NEXI_POS_API_KEY_SECRET": "your-api-key-secret",
        "NEXI_POS_TERMINAL_ID": "your-terminal-id"
      }
    }
  }
}

Amount format

All amounts are integers in ISO 4217 minor units. Do not send floating point values.

Examples:

• SEK 1.00 = 100
• EUR 1.00 = 100
• JPY 1 = 1

The default max amount is 100021, meaning SEK/EUR 1000.21. This allows the documented Nexi simulator/test-case amounts. Set NEXI_POS_MAX_AMOUNT_MINOR to a lower value if your environment should block larger test amounts.

External IDs

external_id is your unique order or payment ID. Use a value that lets you find the payment later, for example order-1001-payment-1.

Rules:

• Use one unique external_id for one transaction.
• Reuse the same external_id only when retrying the same transaction after a timeout, restart, or network problem.
• Use a new external_id for a new order, a new payment attempt, or a different amount.

Reusing an old external_id for a different amount or order can return the old transaction or fail because Nexi treats it as the same transaction request.

Tools

• set_terminal_id - store a terminal ID for this MCP server session.
• get_session_terminal_id - show the current session terminal ID.
• clear_terminal_id - clear the session terminal ID.
• list_test_cases - list documented Nexi simulator/test cases and their trigger amounts.
• create_purchase - low-level purchase call. Can use requested_amount or named test_case.
• take_payment - recommended normal purchase flow. It creates/polls a purchase until Nexi leaves PROCESSING or the timeout is reached. Can use requested_amount or named test_case.
• create_refund - low-level refund call.
• confirm_transaction - confirm a purchase or refund result.
• get_transaction - fetch a transaction by external_id and terminal.
• get_unconfirmed_transactions - list unconfirmed transactions for a terminal.
• get_terminal_status - fetch terminal connection, transaction state, screen, and battery status.
• list_terminal_events - list terminal event stream entries, optionally filtered by event type.

Response guide

All tool responses use this JSON shape:

{
  "ok": true,
  "operation": "take_payment",
  "terminal_id": "terminal-1",
  "external_id": "order-123",
  "state": "AWAITING_CONFIRM",
  "result_code": "SUCCESS",
  "result_description": "Approved",
  "success": true,
  "message": "Payment flow stopped at terminal/current state",
  "user_message": "The card step succeeded, but the transaction is not complete until it is confirmed.",
  "next_action": "Call confirm_transaction to complete the transaction.",
  "summary": {
    "amount": 500,
    "currency": "SEK",
    "state": "AWAITING_CONFIRM",
    "result_code": "SUCCESS",
    "reference": "reference-from-nexi",
    "masked_card": "************0010"
  },
  "transaction": {},
  "raw": {}
}

Field meanings:

• ok: the MCP tool call was handled. It does not always mean that the card payment succeeded.
• success: the payment/refund result was successful. This is true only when result_code is SUCCESS.
• state: the current Nexi transaction state, for example PROCESSING, AWAITING_CONFIRM, CONFIRMED, or COMMITTED.
• result_code: the payment/refund result from Nexi, when available.
• summary: short user-friendly payment details. Use this before inspecting raw.
• user_message: important human-readable warning or context.
• next_action: suggested next step, for example poll again, confirm, or no action needed.
• test_case: included when requested_amount matches a documented Nexi simulator/test case, or when test_case was used as input.
• raw: full Nexi response for debugging and integrations.

Normal payment flow

For most clients, use take_payment for purchases. It calls Nexi purchase repeatedly while the state is PROCESSING, until the total timeout_seconds is reached or Nexi returns a later state such as AWAITING_CONFIRM, CONFIRMED, or COMMITTED.

You can provide the terminal in three ways:

1. pass terminal_id in the tool call;
2. call set_terminal_id once for the session;
3. set NEXI_POS_TERMINAL_ID as an environment fallback.

Recommended flow:

1. Start a payment with take_payment.
2. If the response state is AWAITING_CONFIRM, call confirm_transaction when your business flow is ready.
3. If the response is still PROCESSING, retry later with the same external_id and terminal ID.

Examples

Take a 5 SEK payment

Tool: take_payment

{
  "external_id": "order-1001-payment-1",
  "requested_amount": 500,
  "currency": "SEK",
  "timeout_seconds": 60
}

Run a named Nexi test case

Tool: take_payment

{
  "external_id": "test-issuer-error-1",
  "test_case": "issuer_error",
  "currency": "SEK",
  "timeout_seconds": 60
}

The tool maps issuer_error to requested_amount: 100006. You can also use descriptions or aliases, for example "bank declined".

To list supported names and descriptions, call list_test_cases:

{}

Confirm payment

Tool: confirm_transaction

{
  "external_id": "order-1001-payment-1",
  "result_code": "SUCCESS"
}

Refund 5 SEK

Tool: create_refund

{
  "external_id": "order-1001-refund-1",
  "requested_amount": 500,
  "currency": "SEK",
  "original_purchase_external_id": "order-1001-payment-1"
}

Purchase with environment terminal

Set NEXI_POS_TERMINAL_ID in the environment, then omit terminal_id in the tool call.

Tool: create_purchase

{
  "external_id": "order-1002-payment-1",
  "requested_amount": 500,
  "currency": "SEK"
}

Purchase with explicit terminal

Tool: create_purchase

{
  "terminal_id": "your-terminal-id",
  "external_id": "order-1003-payment-1",
  "requested_amount": 500,
  "currency": "SEK"
}

Recovery after restart

If the server restarts during a payment, use the same external_id and terminal ID.

Tool: get_transaction

{
  "terminal_id": "your-terminal-id",
  "external_id": "order-1001-payment-1"
}

Then check unconfirmed transactions.

Tool: get_unconfirmed_transactions

{
  "terminal_id": "your-terminal-id"
}

You can also check the terminal status.

Tool: get_terminal_status

{
  "terminal_id": "your-terminal-id"
}

If a transaction is waiting for confirmation, confirm it.

Tool: confirm_transaction

{
  "terminal_id": "your-terminal-id",
  "external_id": "order-1001-payment-1",
  "result_code": "SUCCESS"
}

List terminal events

Tool: list_terminal_events

{
  "terminal_id": "your-terminal-id",
  "event_type": "eu.npay.api.pos.v0.TerminalStatus",
  "limit": 20,
  "wait_seconds": 30
}

If wait_seconds is omitted, the tool uses short polling with 0. Set a positive wait_seconds value for long polling.

Use next_token from a previous response to continue the same event list. When next_token is sent, the server does not send a new filter because Nexi keeps the previous filtering criteria.

{
  "terminal_id": "your-terminal-id",
  "next_token": "token-from-previous-response",
  "limit": 20,
  "wait_seconds": 30
}

Confirmation

This MVP does not confirm by default.

When a transaction reaches AWAITING_CONFIRM, call confirm_transaction:

{
  "external_id": "order-1001-payment-1",
  "result_code": "SUCCESS"
}

You can also let take_payment confirm automatically:

{
  "external_id": "order-1002-payment-1",
  "requested_amount": 500,
  "auto_confirm": true
}

Use auto_confirm only when your business flow is ready to accept the transaction result immediately.

SQLite storage and recovery

The server stores payment-relevant state in SQLite at NEXI_POS_STORAGE_PATH.

Stored data includes:

• external ID
• terminal ID
• transaction type
• currency
• requested amount
• state
• result code and description
• confirmation flag
• timestamps
• redacted raw transaction JSON

API credentials are never stored. Card-related fields should be redacted by the storage/client layer.

Recovery workflow after a restart:

1. Call set_terminal_id if the session terminal ID was lost and you do not use NEXI_POS_TERMINAL_ID.
2. Call get_transaction with the known external_id.
3. Call get_unconfirmed_transactions for the terminal.
4. If needed, call confirm_transaction with the correct result_code.

SQLite improves recovery, but it is not a full production operations system. Keep your own order records and reconcile with Nexi when needed.

Troubleshooting

HTTP 401 or 403

Check NEXI_POS_API_KEY_ID and NEXI_POS_API_KEY_SECRET. Also check that the credentials are valid for the selected NEXI_POS_BASE_URL environment, for example sandbox versus production. The credentials and terminal ID are generated outside this MCP server.

Missing terminal ID

Pass terminal_id in the tool call, call set_terminal_id, or set NEXI_POS_TERMINAL_ID. There is no default terminal ID.

Amount exceeds max

The server blocks amounts above NEXI_POS_MAX_AMOUNT_MINOR. Lower requested_amount or raise NEXI_POS_MAX_AMOUNT_MINOR for your environment. Amounts are minor units, so SEK 5.00 is 500. The default 100021 allows Nexi's documented test-case trigger amounts.

Transaction stuck in PROCESSING

Do not create a new transaction immediately. Retry take_payment with the same external_id and terminal ID, or call get_transaction. If it remains in PROCESSING, check the terminal and Nexi status before deciding whether to start a new payment with a new external_id.

Transaction awaiting confirm

If state is AWAITING_CONFIRM, the card step has succeeded but the transaction is not complete. Call confirm_transaction with the same external_id and terminal ID when you are ready to accept the result. You can also use auto_confirm with take_payment for flows where immediate confirmation is correct.

Reused external_id

Use the same external_id only to retry the same transaction. If the order, amount, or payment attempt is different, use a new external_id.

Nexi simulator/test cases

Nexi documents special test-case amounts that can be used in sandbox and production simulator testing. The server detects these amounts and adds test_case information to responses. You can also trigger them by name or description with test_case instead of remembering the amount.

Examples:

• test_case: "instant_success" -> requested_amount: 100002
• test_case: "bank declined" -> requested_amount: 100006
• requested_amount: 100017 -> response includes the 10% tip test-case information

Available cases:

| Name | Amount | Category | Description | | --- | ---: | --- | --- | | successful_2s_delay | 100001 | success | Successful transaction with 2-second delay | | instant_success | 100002 | success | Instant successful transaction (0 seconds) | | rejected_by_processor | 100003 | error | Transaction rejected by payment processor | | customer_cancelled | 100004 | error | Transaction aborted (customer cancelled) | | card_removed | 100005 | error | Card removed during processing | | issuer_error | 100006 | error | Issuer error (bank declined) | | internal_system_error | 100007 | error | Internal system error | | network_connectivity_error | 100008 | error | Network connectivity error | | payment_method_not_accepted | 100009 | error | Card/payment method not accepted | | contactless_pin_verified | 100010 | payment_method | Successful PIN-verified contactless transaction | | contactless_cardholder_verification | 100011 | payment_method | Successful contactless with cardholder verification | | chip_without_pin | 100012 | payment_method | Successful chip card without PIN | | chip_with_pin | 100013 | payment_method | Successful chip card with PIN | | magstripe_signature | 100014 | payment_method | Successful magnetic stripe with signature | | magstripe_pin | 100015 | payment_method | Successful magnetic stripe with PIN | | chip_with_pin_alternative | 100016 | payment_method | Successful chip card with PIN (alternative mode) | | tip_10_percent | 100017 | special_feature | Successful transaction with 10% tip added | | surcharge_1_5_percent | 100018 | special_feature | Successful transaction with 1.5% surcharge | | dcc_enabled | 100019 | special_feature | Successful transaction with Dynamic Currency Conversion enabled | | success_30s_delay | 100020 | success | Successful transaction with 30-second delay | | loyalty_link_identity | 100021 | special_feature | Successful transaction with Nexi Loyalty Link customer identity in response |

Implementation notes for integration

The MCP tool layer expects these core modules to exist:

• src/config.ts exporting getConfig() with API, currency, terminal fallback, max amount, request timeout, and storage path settings.
• src/nexi-client.ts exporting NexiClient with purchase, refund, confirm, getTransaction, getUnconfirmedTransactions, getTerminalStatus, and listTerminalEvents methods.
• src/storage/sqlite-store.ts exporting SQLiteStore with saveIntent, updateTransaction, and markConfirmed methods.

These modules are intentionally separate from the MCP tool code so the API client and storage can be tested independently.