Nexi It XPay Payment Gateway API

Name: XPay Payment Gateway API
Brand: XPay Payment Gateway API
Availability: InStock

✓ Official Vendor SpecPaymentsPayment ProcessingapiKey16 EndpointsREST

For Agents

Process card payments, refunds, captures, and pay-by-link orders through Nexi's XPay gateway. Includes hosted payment pages, contract management, and Google Pay support.

Install Jentic One Beta

Connect the XPay Payment Gateway API to your agent

Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the XPay Payment Gateway API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.

Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.

Step 1: Jentic One Host machine

# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh

Step 2: Agent machine

# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register       # connects your agent to your Jentic One instance

Jentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.

Capabilities

What an agent can do with XPay Payment Gateway API.

Create hosted payment page orders via POST /orders/hpp for redirect-based checkout flows

Generate pay-by-link orders with POST /v2/orders/paybylink so payers can complete checkout from an emailed URL

Process refunds, captures, and cancellations on existing payments through /operations/{operationId} endpoints

GET STARTED

Start building with XPay Payment Gateway API

Explore with Jentic

View OpenAPI Document

Nexi XPay is the Italian payments gateway from Nexi, one of Europe's largest payment processors. The API supports hosted payment pages, pay-by-link orders, three-step direct payments, card verification, Google Pay, and back-office operations including refunds, captures, and cancellations. Sixteen endpoints are split between order creation and retrieval (/orders, /orders/hpp, /v2/orders/paybylink), back-office operations on existing orders (/operations, /operations/{operationId}/refunds, /captures, /cancels), and configuration calls for customer contracts and payment methods. Authentication uses an X-Api-Key header.

Use Cases

Patterns agents use XPay Payment Gateway API for, with concrete tasks.

★ Hosted Checkout for Italian E-Commerce

Italian e-commerce merchants integrate XPay's hosted payment page to accept cards without holding card data themselves. The merchant calls POST /orders/hpp with the cart amount and metadata, redirects the customer to the returned URL, and Nexi handles 3D Secure, card capture, and PSD2 SCA compliance. The merchant then polls GET /orders/{orderId} to confirm the final status before fulfilling the order.

Create a hosted payment page order for 49.99 EUR with a unique merchant orderId, then poll GET /orders/{orderId} until the status is final

Pay-by-Link for Service Invoices

Service businesses send pay-by-link URLs to their customers via email or messaging instead of processing cards over the phone. POST /v2/orders/paybylink creates the link and POST /paybylink/{linkId}/cancels invalidates it if needed. GET /orders/paybylink lists all outstanding links for a finance team's reconciliation view.

Create a pay-by-link for 1500 EUR with a 7-day expiry and email the returned URL to the customer

Back-Office Refunds and Captures

Customer support teams use the /operations endpoints to issue refunds and captures from internal tooling. POST /operations/{operationId}/refunds processes a refund tied to a specific original operation, POST /captures captures a previously authorised amount, and POST /cancels voids an unsettled operation. GET /operations/{operationId}/actions lists which of these are valid for the current state, so the agent can present only the allowed buttons.

Refund operation op_98765 in full and verify the refund status moves to completed via GET /operations/{operationId}

Agent-Driven Payment Operations

An AI agent uses the XPay API through Jentic to handle payment operations triggered by upstream events — a support ticket asking for a refund, a customer requesting a deactivated card contract, or an automated dunning workflow. The agent calls GET /operations/{operationId}/actions first to discover which operations are valid before posting the refund, capture, or cancel.

When a support ticket requests a refund, look up the operationId on the order, confirm refund is in the allowed actions, then issue the refund

Key Endpoints

16 endpoints — nexi xpay is the italian payments gateway from nexi, one of europe's largest payment processors.

METHOD

PATH

DESCRIPTION

POST

/orders/hpp

Create a hosted payment page order

GET

/orders/{orderId}

Retrieve an order's current status

POST

/v2/orders/paybylink

Create a pay-by-link payment order

POST

/operations/{operationId}/refunds

Refund an operation

POST

/operations/{operationId}/captures

Capture an authorised operation

POST

/operations/{operationId}/cancels

Cancel an operation

GET

/operations/{operationId}/actions

List valid actions for an operation

GET

/payment_methods

List configured payment methods

POST

/orders/hpp

Create a hosted payment page order

GET

/orders/{orderId}

Retrieve an order's current status

POST

/v2/orders/paybylink

Create a pay-by-link payment order

POST

/operations/{operationId}/refunds

Refund an operation

POST

/operations/{operationId}/captures

Capture an authorised operation

Why Jentic?

Three things that make agents converge on Jentic-routed access.

Credential isolation

Nexi XPay X-Api-Key values are stored encrypted in the Jentic vault and injected on each request. The merchant key never enters the agent's prompt, response, or log output, which matters because the same key authorises captures and refunds on real money.

Intent-based discovery

Agents search Jentic for intents like 'refund a payment on Nexi XPay' or 'create a pay-by-link order' and Jentic returns the matching operation with its request schema, so the agent calls the right /operations or /orders endpoint without reading the XPay docs.

Time to first call

Direct integration: 3-5 days to wire the X-Api-Key header, model orders and operations, build refund and capture flows, and validate against the sandbox at xpaysandbox.nexigroup.com. Through Jentic: under an hour for a single operation — search, load schema, execute.

FAQs

Specific to using XPay Payment Gateway API through Jentic.

What authentication does the Nexi XPay API use?

XPay uses an API key sent in the X-Api-Key header on every request. Through Jentic the key sits in the encrypted vault and is injected at execution time, so the merchant key never appears in the agent's prompt context.

Can I issue a partial refund with the XPay API?

Yes. POST /operations/{operationId}/refunds accepts a refund amount in the request body, so an agent can refund less than the original capture if the merchant policy allows it. Call GET /operations/{operationId}/actions first to confirm refund is valid for the current operation state.

What payment methods does the Nexi XPay API support?

The hosted payment page covers cards (Visa, Mastercard, and the Italian PagoBancomat circuit), Google Pay, and pay-by-link flows. GET /payment_methods returns the list configured for a specific merchant — what is offered to the shopper depends on contract terms with Nexi.

How do I create a pay-by-link order through Jentic?

Search Jentic for 'create a pay-by-link order on nexi xpay', load the POST /v2/orders/paybylink schema, and execute with the amount, currency, and expiry. Jentic injects the X-Api-Key header automatically and the response includes the URL to send to the customer.

Does the XPay API support PSD2 strong customer authentication?

Yes. The hosted payment page handles 3D Secure 2 challenges and SCA exemptions in line with PSD2, so merchants do not have to embed the challenge flow themselves. The API simply returns the order status once the cardholder completes authentication.

Nexi It XPay Payment Gateway API

Connect the XPay Payment Gateway API to your agent

Capabilities

Start building with XPay Payment Gateway API

Use Cases

Key Endpoints

Why Jentic?

Related APIs

FAQs