PagoPA Create API

Create operation.

GitHub OpenAPI

Operations 1

POST /activations RTP activation initiated by the Payer's RTP Service Provider #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/pagopa:pagopa-create-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

pagopa-create-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: RTP Activation API. Create API
  version: 1.0.0
  description: 'This API is used by Payer Service Providers (PSPs, banks, etc.) to manage

    RTP activations.'
  contact:
    name: PagoPA S.p.A.
    email: rtp@pagopa.it
servers:
- description: Development/Test
  url: https://api-rtp.dev.cstar.pagopa.it/rtp/activation
  x-internal: true
- description: User Acceptance Test
  url: https://api-rtp.uat.cstar.pagopa.it/rtp/activation
  x-internal: false
- description: Production
  url: https://api-rtp.cstar.pagopa.it/rtp/activation
  x-internal: false
tags:
- name: Create
  description: Create operation.
paths:
  /activations:
    post:
      operationId: activate
      summary: RTP activation initiated by the Payer's RTP Service Provider
      description: 'A Payer''s Service Provider calls this to register one of their users (Payers) for the RTP service.

        This operation creates a record that links the Payer''s fiscal code to the Service Provider''s ID,

        officially enabling them to receive payment requests.'
      tags:
      - Create
      security:
      - oAuth2:
        - admin_rtp_activations
        - write_rtp_activations
      parameters:
      - $ref: '#/components/parameters/RequestId'
      - $ref: '#/components/parameters/Version'
      requestBody:
        $ref: '#/components/requestBodies/CreateOrUpdateActivation'
      responses:
        '201':
          $ref: '#/components/responses/CreateActivation'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/Error'
components:
  schemas:
    Type2Error:
      description: Error details returned by the APIM.
      type: object
      additionalProperties: false
      properties:
        statusCode:
          $ref: '#/components/schemas/StatusCode'
        message:
          $ref: '#/components/schemas/ErrorDescription'
      required:
      - statusCode
      - message
      example:
        statusCode: 401
        message: Invalid JWT.
    RequestId:
      description: Identifier of the request.
      type: string
      format: uuid
      pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
      minLength: 36
      maxLength: 36
      example: bd615b4a-066d-443e-8dd2-a28a39931fef
    AccessControlAllowOrigin:
      description: 'Indicates whether the response can be shared with requesting code from

        the given origin.

        '
      type: string
      pattern: ^[ -~]{1,2048}$
      minLength: 1
      maxLength: 2048
    Type1Error:
      description: List of errors returned by the application.
      type: object
      additionalProperties: false
      properties:
        errors:
          type: array
          minItems: 1
          maxItems: 32
          items:
            $ref: '#/components/schemas/Error'
      required:
      - errors
      example:
        errors:
        - code: 01021000E
          description: Wrong party identifier
    RetryAfter:
      description: 'The number of seconds to wait before allowing a follow-up request.

        '
      type: integer
      format: int32
      minimum: 1
      maximum: 240
    PartyId:
      description: 'Unique and unambiguous identification of a party.


        It is used as identifier of the Payer''s RTP Service Provider (N001) and

        for Payee''s RTP Service Provider (N002).


        A Service Provider is identified by its BIC (Bank Identification Code)

        if it is a PSP, otherwise it is identified by its VAT identification

        number (Value Added Tax id).

        '
      oneOf:
      - $ref: '#/components/schemas/Bic'
      - $ref: '#/components/schemas/Vat'
    RateLimitReset:
      description: The number of seconds left in the current period.
      type: integer
      format: int32
      minimum: 1
      maximum: 60
    ActivationReq:
      description: 'Data of a RTP activation.

        '
      type: object
      properties:
        payer:
          $ref: '#/components/schemas/Payer'
      required:
      - payer
      example:
        payer:
          fiscalCode: RSSMRA85T10A562S
          rtpSpId: '12345678911'
    Version:
      description: Version of the required API.
      type: string
      pattern: ^[ -~]{1,64}$
      minLength: 1
      maxLength: 64
      example: v1
    TakeOverOtpLocation:
      description: URL to do a takeover on a existing activation user.
      type: string
      format: uri
      pattern: ^[ -~]{1,2048}$
      minLength: 1
      maxLength: 2048
      example: https://rtp.cstar.pagopa.it/activations/takeover/d0d654e6-97da-4848-b568-99fedccb642b
    Error:
      description: Error details.
      type: object
      additionalProperties: false
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        description:
          $ref: '#/components/schemas/ErrorDescription'
      required:
      - code
      - description
      example:
        code: 01021000E
        description: Wrong party identifier
    Payer:
      description: 'Payer data.

        '
      type: object
      additionalProperties: false
      properties:
        fiscalCode:
          $ref: '#/components/schemas/FiscalCode'
        rtpSpId:
          $ref: '#/components/schemas/PartyId'
      required:
      - fiscalCode
      - rtpSpId
      example:
        fiscalCode: RSSMRA85T10A562S
        rtpSpId: '12345678911'
    Vat:
      description: Value Added Tax.
      type: string
      pattern: ^[0-9]{11}$
      minLength: 11
      maxLength: 11
      example: '12345678911'
    Bic:
      description: Bank Identification Code.
      type: string
      pattern: ^[A-Z0-9]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3}){0,1}$
      minLength: 8
      maxLength: 11
      example: UNCRITMM
    FiscalCode:
      description: 'Fiscal code.


        It is used as identifier of the Payer (P009) and of the Payee (E005).

        '
      type: string
      pattern: ^(?:(?:[A-Z][AEIOUX][AEIOUX]|[B-DF-HJ-NP-TV-Z]{2}[A-Z]){2}(?:[\dLMNP-V]{2}(?:[A-EHLMPR-T](?:[04LQ][1-9MNP-V]|[15MR][\dLMNP-V]|[26NS][0-8LMNP-U])|[DHPS][37PT][0L]|[ACELMRT][37PT][01LM]|[AC-EHLMPR-T][26NS][9V])|(?:[02468LNQSU][048LQU]|[13579MPRTV][26NS])B[26NS][9V])(?:[A-MZ][1-9MNP-V][\dLMNP-V]{2}|[A-M][0L](?:[1-9MNP-V][\dLMNP-V]|[0L][1-9MNP-V]))[A-Z]|\d{11})$
      minLength: 11
      maxLength: 16
      example: RSSMRA85T10A562S
    Errors:
      description: 'Error details.

        The format depends on the component which returns it.

        '
      oneOf:
      - $ref: '#/components/schemas/Type1Error'
      - $ref: '#/components/schemas/Type2Error'
      - $ref: '#/components/schemas/Type3Error'
    StatusCode:
      description: HTTP status code.
      type: integer
      format: int32
      minimum: 0
      maximum: 999
      example: 401
    ErrorCode:
      description: "Error code following the format ZZXXKYYYT where:\n  - ZZ: Domain identifier\n  - XX: Error category (01=Authentication, 02=Validation, etc.)\n  - K: Method type (1=POST, etc.)\n  - YYY: Detailed error code\n  - T: Severity (F=Fatal, E=Error, W=Warning)\n"
      type: string
      enum:
      - 01021000E
      - 01021001E
      - 01021002E
      - 01021003E
      - 01021004E
      - 01021009E
      - 01011000E
      - 01011001E
      - 01011002E
      - 01011003F
      - 01011004E
      - 01011005E
      - 01011006F
      - 01021010E
      - 01031000E
      - 01031001E
      - 01021011E
      - 01021012E
      - 01051000E
      - 01051001E
      - 01091000F
      - 01091001F
      - 01021005E
      - 01021006E
      - 01021007E
      - 01041000E
      - 01041001E
      - 01021008E
      - 01021013E
      minLength: 9
      maxLength: 9
      example: 01021000E
    ActivationLocation:
      description: URL of the RTP activation resource.
      type: string
      format: uri
      pattern: ^[ -~]{1,2048}$
      minLength: 1
      maxLength: 2048
      example: https://rtp.cstar.pagopa.it/activations/d0d654e6-97da-4848-b568-99fedccb642b
    Type3Error:
      description: Error details returned by the framework.
      type: object
      additionalProperties: false
      properties:
        timestamp:
          description: Timestamp the error occurred.
          type: string
          format: date-time
          minLength: 19
          maxLength: 29
          pattern: ^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$
        path:
          description: API path where the error occurred.
          type: string
          pattern: ^[ -~]{1,1024}$
          minLength: 1
          maxLength: 1024
        status:
          $ref: '#/components/schemas/StatusCode'
        error:
          $ref: '#/components/schemas/ErrorDescription'
        requestId:
          description: ID of the request.
          type: string
          pattern: ^[ -~]{1,128}$
          minLength: 1
          maxLength: 128
      required:
      - timestamp
      - path
      - status
      - error
      - requestId
      example:
        timestamp: '2024-12-31T09:54:01.763+00:00'
        path: /activations
        status: 415
        error: Unsupported Media Type
        requestId: 3fb00d0f-416
    RateLimitLimit:
      description: The number of allowed requests in the current period.
      type: integer
      format: int32
      minimum: 1
      maximum: 240
    ErrorDescription:
      description: Error description.
      type: string
      pattern: ^[ -~]{0,256}$
      minLength: 0
      maxLength: 256
      example: Wrong party identifier
  headers:
    RetryAfter:
      description: 'The number of seconds to wait before allowing a follow-up request.

        '
      required: false
      schema:
        $ref: '#/components/schemas/RetryAfter'
    RateLimitReset:
      description: The number of seconds left in the current period.
      required: false
      schema:
        $ref: '#/components/schemas/RateLimitReset'
    AccessControlAllowOrigin:
      description: 'Indicates whether the response can be shared with requesting code

        from the given origin.

        '
      required: false
      schema:
        $ref: '#/components/schemas/AccessControlAllowOrigin'
    RateLimitLimit:
      description: The number of allowed requests in the current period.
      required: false
      schema:
        $ref: '#/components/schemas/RateLimitLimit'
  responses:
    Error:
      description: Response returned when an unexpected error occurred.
      headers:
        Access-Control-Allow-Origin:
          $ref: '#/components/headers/AccessControlAllowOrigin'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
        text/*:
          schema:
            type: string
            pattern: ^[ -~]{0,65535}$
            maxLength: 65535
    InternalServerError:
      description: Internal server error. An unexpected error occurred on the server side.
      headers:
        Access-Control-Allow-Origin:
          $ref: '#/components/headers/AccessControlAllowOrigin'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
        text/*:
          schema:
            type: string
            pattern: ^[ -~]{0,65535}$
            maxLength: 65535
    CreateActivation:
      description: Response returned when a RTP activation is requested.
      headers:
        Access-Control-Allow-Origin:
          $ref: '#/components/headers/AccessControlAllowOrigin'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Location:
          description: URL of the activation resource.
          required: true
          schema:
            $ref: '#/components/schemas/ActivationLocation'
    TooManyRequestsError:
      description: Too many requests. The client has exceeded the rate limit or quota.
      headers:
        Access-Control-Allow-Origin:
          $ref: '#/components/headers/AccessControlAllowOrigin'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
        text/*:
          schema:
            type: string
            pattern: ^[ -~]{0,65535}$
            maxLength: 65535
    ForbiddenError:
      description: Forbidden. The caller has insufficient permissions or the provided identity does not match the token subject.
      headers:
        Access-Control-Allow-Origin:
          $ref: '#/components/headers/AccessControlAllowOrigin'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
        text/*:
          schema:
            type: string
            pattern: ^[ -~]{0,65535}$
            maxLength: 65535
    BadRequestError:
      description: Bad request. The request was malformed or contained invalid parameters.
      headers:
        Access-Control-Allow-Origin:
          $ref: '#/components/headers/AccessControlAllowOrigin'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
        text/*:
          schema:
            type: string
            pattern: ^[ -~]{0,65535}$
            maxLength: 65535
    ConflictError:
      description: Conflict. An activation for this Payer already exists. The Location header points to the existing resource.
      headers:
        Access-Control-Allow-Origin:
          $ref: '#/components/headers/AccessControlAllowOrigin'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Location:
          description: URL to do a takeover on an existing activation user.
          required: true
          schema:
            $ref: '#/components/schemas/TakeOverOtpLocation'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    UnsupportedMediaTypeError:
      description: Unsupported media type. The Content-Type header specifies a format not supported by this API.
      headers:
        Access-Control-Allow-Origin:
          $ref: '#/components/headers/AccessControlAllowOrigin'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
        text/*:
          schema:
            type: string
            pattern: ^[ -~]{0,65535}$
            maxLength: 65535
    UnauthorizedError:
      description: Unauthorized. Access token is missing or invalid.
      headers:
        Access-Control-Allow-Origin:
          $ref: '#/components/headers/AccessControlAllowOrigin'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
        text/*:
          schema:
            type: string
            pattern: ^[ -~]{0,65535}$
            maxLength: 65535
  parameters:
    RequestId:
      name: RequestId
      in: header
      description: Identifier of the request.
      required: true
      schema:
        $ref: '#/components/schemas/RequestId'
    Version:
      name: Version
      in: header
      description: Version of the required API.
      required: true
      schema:
        $ref: '#/components/schemas/Version'
  requestBodies:
    CreateOrUpdateActivation:
      description: Request to create or update a RTP activation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ActivationReq'
  securitySchemes:
    oAuth2:
      description: 'A bearer token in the format of a JWS and conforms to the specifications

        included in RFC8725.

        '
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api-mcshared.cstar.pagopa.it/auth-itn/realms/srtp/protocol/openid-connect/token
          refreshUrl: https://api-mcshared.cstar.pagopa.it/auth-itn/realms/srtp/protocol/openid-connect/token
          scopes:
            admin_rtp_activations: Grants full administrative access to all activations.
            write_rtp_activations: Grants permission to create, update, or delete activations.
            read_rtp_activations: Read RTP activation belonging to the requesting subject.
            read_rtp_all: Read all RTP activations.