PagoPa S.p.A. PagoPA GPD API

Name: PagoPA GPD API
Brand: PagoPA GPD API
Availability: InStock

✓ Official Vendor SpecFintechPaymentsapiKey9 EndpointsREST

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

Install Jentic One Beta

Connect the PagoPA GPD API to your agent

Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the PagoPA GPD 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 PagoPA GPD API.

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

GET STARTED

Start building with PagoPA GPD API

Explore with Jentic

View OpenAPI Document

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.

Use Cases

Patterns agents use PagoPA GPD API for, with concrete tasks.

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

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.

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.

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.

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.

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

Key Endpoints

9 endpoints — pagopa gpd (gestione posizioni debitorie) api manages debt positions for italian public administration organizations.

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

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

Why Jentic?

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

Credential isolation

PagoPA API keys (Ocp-Apim-Subscription-Key) are stored encrypted in the Jentic vault and injected as a header at execution time. Raw keys never appear in agent prompts, transcripts, or response payloads.

Intent-based discovery

Agents search by intent such as 'publish a pagopa debt position' or 'update debt position IBAN' and Jentic returns the matching endpoint with its schema and path parameters.

Time to first call

Direct PagoPA GPD integration: 1-2 days to model debt positions, payment options, transfers, and status lifecycle. Through Jentic: under 1 hour — search, load schema, execute.

FAQs

Specific to using PagoPA GPD API through Jentic.

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.

PagoPa S.p.A. PagoPA GPD API

Connect the PagoPA GPD API to your agent

Capabilities

Start building with PagoPA GPD API

Use Cases

Key Endpoints

Why Jentic?

Related APIs

FAQs