canonical: https://jentic.com/apis/nexi.it/nexi

# Nexi It XPay Payment Gateway API

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.

## For AI 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.

## Scope

Does not handle accounting reconciliation, payouts to merchant bank accounts, or chargeback dispute submission - use for payment authorisation, capture, refund, and pay-by-link operations only.

## Capabilities

- 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
- Retrieve order status and the list of allowed actions for any orderId or operationId
- Manage customer payment contracts via `/contracts/customers/{customerId}` and deactivate them when needed
- List the payment methods available to a merchant configuration through GET /payment_methods

## Use cases

### 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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

| 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 |

## Key resources

- **Orders** — Create hosted payment page orders, retrieve order details, and list orders
- **Pay-by-Link** — Generate, retrieve, list, and cancel pay-by-link payment orders
- **Operations** — Retrieve operations, list available actions, and execute refunds, captures, and cancellations
- **Contracts** — Read and deactivate stored customer payment contracts
- **Payment Methods** — List payment methods configured for the merchant

## Why Jentic

- **Setup:** Wiring Nexi XPay by hand means learning its API-key request header auth, choosing between the production and sandbox hosts, and tracking order and operation ids across authorisation, capture, and refund yourself. Through Jentic you install once, import the XPay Payment Gateway API from the API Directory, store the merchant key once, and your agent calls it.
- **Permission scoping:** XPay puts the operation id in the URL path (`/operations/{operationId}/refunds`), so a rule can pin your agent to actions on one operation. You choose the operations it may call, so money-moving ones like refunds, captures, or cancels are not included unless you deliberately add them.
- **Credential handling:** Your Nexi XPay merchant key is stored once, encrypted, by your own Jentic One instance and injected into the API-key request header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'refund a payment on Nexi XPay' or 'create a pay-by-link order', and Jentic returns the matching XPay operation with its request schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stripe API** — Stripe is a global payment processor with PaymentIntents, Checkout, and PaymentLinks across many countries
- **Adyen API** — Adyen is a European acquirer with hosted checkout, refund, and capture endpoints similar to XPay
- **Nexi Group API** — Nexi Group exposes Swish checkout and Nordic payment processing on the api.nexigroup.com host

## FAQ

### 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.

### Can I limit what my agent is allowed to do with the Nexi XPay API?

Yes. Because you run Jentic One yourself, your own rules decide which XPay operations and credentials the agent may use, so you can allow read-only calls like GET `/orders/{orderId}` and GET `/operations/{operationId}/actions` while withholding the money-moving ones. Refunds, captures, and cancels on `/operations/{operationId}` are not available to the agent unless you deliberately add them. Since XPay puts the operation id in the URL path, a rule can even pin the agent to actions on a single operation. Your merchant key stays with your instance and is injected at execution time, never entering the agent's prompt or logs.