canonical: https://jentic.com/apis/pagopa.it/pagopa-gpd

# PagoPa S.p.A. PagoPA GPD API

PagoPA GPD (Gestione Posizioni Debitorie) API manages debt positions for Italian public administration organizations. The API provides CRUD operations for debt positions, payment options, and transfers, including lifecycle actions like publish, invalidate, and mark-as-paid. Organizations use it to create payment positions with IUPDs (unique identifiers), attach multiple payment options with NAV codes, configure transfers to IBANs, and track status transitions from DRAFT through PUBLISHED, VALID, PAID, and REPORTED states. Authentication uses Ocp-Apim-Subscription-Key header for Azure APIM integration.

## For AI agents

Manage Italian public administration debt positions - create, update, delete, publish, invalidate, and mark payment options as paid, with transfer IBAN updates and status filtering.

## Scope

Does not process actual payments, handle citizen authentication, or interact with banks directly - use for debt position lifecycle management, status tracking, and IBAN configuration only. Payment processing happens within the broader pagoPA platform.

## Capabilities

- Create and update debt positions with unique IUPD identifiers per organization fiscal code
- Attach one or more payment options to a debt position, each with a NAV code and due date
- Configure transfers per payment option with IBAN, amount, category, and remittance info
- Publish debt positions to transition from DRAFT to PUBLISHED state for payment processing
- Invalidate debt positions to mark them as no longer payable
- Mark payment options as already paid with payment date and method details
- Update IBANs across multiple transfers in batch for an organization
- List debt positions with filters on due date, payment date, status, and pagination

## Use cases

### Create and Publish Debt Position

An Italian municipality creates a new debt position for a citizen (companyName, fiscalCode, type) with one or more payment options, each containing transfers to IBANs representing the amounts owed to different departments. The position is created in DRAFT state via POST /debtpositions, then published via POST `/debtpositions/{iupd}/publish` to transition it to PUBLISHED, making it visible in the pagoPA payment system for citizens to pay.

Example prompt: POST `/organizations/{organizationfiscalcode}/debtpositions` with PaymentPositionModel containing iupd, companyName, fiscalCode, type, and paymentOption array. Then POST `/organizations/{organizationfiscalcode}/debtpositions/{iupd}/publish` to activate.

### Batch IBAN Migration

A creditor organization migrates from an old IBAN to a new one across all unpaid debt positions. Using PATCH `/debtpositions/transfers` with oldIban and newIban, the API updates up to 1000 transfer records at once, preserving all other transfer details while swapping the bank account. This supports organizational bank account changes without recreating debt positions.

Example prompt: PATCH `/organizations/{organizationfiscalcode}/debtpositions/transfers`?oldIban={old}&limit=1000 with UpdateTransferIbanMassiveModel containing newIban and newPostalIban.

### Mark Payment as Already Paid Outside PagoPA

When a citizen pays a debt position through a channel outside the pagoPA platform (e.g., bank transfer, cash at a government office), the organization uses POST `/paymentoptions/paids/{nav}` to record the payment in GPD. This prevents duplicate payment attempts and updates the debt position status to PAID or PARTIALLY_PAID, reconciling the external payment with the internal debt ledger.

Example prompt: POST `/organizations/{organizationfiscalcode}/paymentoptions/paids/{nav}` with AlreadyPaidPaymentOptionModel containing paymentDate, paymentMethod, pspCompany, and fee details.

### Query Debt Positions by Status and Date

An SRE dashboard or finance reconciliation job lists debt positions filtered by status (VALID, PAID, EXPIRED), due date range, or payment date range. GET /debtpositions supports pagination, ordering by INSERTED_DATE/IUPD/STATUS/COMPANY_NAME, and mutually exclusive date filters for due_date vs payment_date. This supports reporting, audit, and automated reconciliation workflows.

Example prompt: GET `/organizations/{organizationfiscalcode}/debtpositions`?status=VALID&due_date_from=2026-05-01&due_date_to=2026-05-31&page=0&limit=50&orderby=INSERTED_DATE&ordering=DESC.

### AI Agent for GPD Lifecycle Management

An AI agent automates debt position lifecycle tasks for a municipality: creating positions from ERP exports, publishing them, marking payments recorded in external systems, and invalidating positions that are forgiven or expired. Through Jentic, the agent searches by intent (e.g., 'publish a pagopa debt position'), loads the schema, and executes with the Ocp-Apim-Subscription-Key injected securely.

Example prompt: Use Jentic search 'publish pagopa debt position' to find POST `/debtpositions/{iupd}/publish`, load schema, execute with organizationfiscalcode and iupd.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/organizations/{organizationfiscalcode}/debtpositions` | Create a new debt position |
| GET | `/organizations/{organizationfiscalcode}/debtpositions` | List debt positions with filters |
| GET | `/organizations/{organizationfiscalcode}/debtpositions/{iupd}` | Get debt position details |
| PUT | `/organizations/{organizationfiscalcode}/debtpositions/{iupd}` | Update a debt position |
| DELETE | `/organizations/{organizationfiscalcode}/debtpositions/{iupd}` | Delete a debt position |
| POST | `/organizations/{organizationfiscalcode}/debtpositions/{iupd}/publish` | Publish a debt position |
| POST | `/organizations/{organizationfiscalcode}/debtpositions/{iupd}/invalidate` | Invalidate a debt position |
| PATCH | `/organizations/{organizationfiscalcode}/debtpositions/transfers` | Batch update transfer IBANs |

## Key resources

- **Debt Positions** — Payment positions with unique IUPD, organization fiscal code, debtor details, status lifecycle, and multiple payment options
- **Payment Options** — Individual payable items within a debt position, each with NAV code, amount, due date, and transfers
- **Transfers** — IBAN destinations within a payment option, specifying amounts owed to different accounts or categories
- **Organization Fiscal Code** — Italian fiscal code identifying the creditor public administration entity

## Why Jentic

- **Setup:** Wiring PagoPA GPD by hand means handling its Ocp-Apim-Subscription-Key auth, choosing between the UAT and production platform.pagopa.it hosts, and building your own retry and error handling. Through Jentic you install once, import the PagoPA GPD API from the API Directory, store the subscription key once, and your agent calls it.
- **Permission scoping:** PagoPA GPD puts the organization fiscal code in the URL path (`/organizations/{organizationfiscalcode}/debtpositions`), so a rule can pin your agent to one organization: it works within that organization and nothing else. You choose the operations it may call, so deleting or invalidating a debt position is not included unless you add it.
- **Credential handling:** Your PagoPA subscription key is stored once, encrypted, by your own Jentic One instance and injected as the Ocp-Apim-Subscription-Key header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'publish a PagoPA debt position' or 'update debt position IBAN', and Jentic returns the matching PagoPA GPD operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stripe API** — Stripe provides a general-purpose payment and invoicing API, while PagoPA GPD is specific to Italian public administration debt positions.

## FAQ

### What authentication does the PagoPA GPD API use?

The PagoPA GPD API uses API key authentication via the Ocp-Apim-Subscription-Key header for Azure API Management. Through Jentic, keys are stored encrypted and injected at execution time so they never enter the agent's context.

### What is an IUPD in the PagoPA GPD API?

IUPD (Unique Identifier of Debt Position) is a globally unique identifier for a debt position, typically formatted as the organization fiscal code plus a UUID. It is the responsibility of the creditor entity (EC) to ensure uniqueness.

### Can I update the IBAN for multiple debt positions at once?

Yes. Use PATCH `/organizations/{organizationfiscalcode}/debtpositions/transfers` with the oldIban query parameter and the newIban in the request body. This updates up to 1000 transfers in a single call.

### How do I publish a debt position?

After creating a debt position in DRAFT state, call POST `/organizations/{organizationfiscalcode}/debtpositions/{iupd}/publish` to transition it to PUBLISHED, making it visible and payable in the pagoPA system.

### Is the PagoPA GPD API free?

The PagoPA platform is provided by PagoPa S.p.A. for Italian public administrations. Access to the GPD API requires registration and approval from PagoPA. Pricing and terms are documented at www.pagopa.gov.it.

### Can I mark a payment as paid if it was made outside pagoPA?

Yes. Use POST `/organizations/{organizationfiscalcode}/paymentoptions/paids/{nav}` with payment details to record an external payment, updating the debt position status to PAID or PARTIALLY_PAID.

### Can I limit what my agent is allowed to do with the PagoPA GPD API?

Yes. Because Jentic One is self-hosted, your own rules decide which PagoPA GPD operations and credentials the agent may use. Since the API puts the organization fiscal code in the URL path, you can pin the agent to a single organization so it works within that entity and nothing else. You also choose the exact operations it may call, so you can allow creating and publishing debt positions while excluding destructive actions like deleting or invalidating a position unless you explicitly add them.