openapi: 3.0.1
info:
  version: 1.0.0
  title: pagoPA checkout-EC API
  contact:
    name: pagoPA checkout team
    url: https://portal.uat.platform.pagopa.it
  description: Documentation of the pagoPA checkout API here.
servers:
  - url: https://api.uat.platform.pagopa.it/checkout/ec/v1
    description: host for UAT environment
  - url: https://api.platform.pagopa.it/checkout/ec/v1
    description: host for PROD environment
paths:
  /carts:
    post:
      operationId: PostCarts
      description: create a cart
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CartRequest"
        required: true
      responses:
        "302":
          description: Redirect
          headers:
            location:
              description: CheckOut Url
              schema:
                type: string
                format: uri
        "400":
          description: Bad request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ProblemJson"
            application/json:
              examples:
                response:
                  value:
                    type: https://checkout.pagopa.it/problems/bad-request
                    title: Bad Request
                    status: 400
                    detail: missing fiscalCode
        "422":
          description: Unprocessable Entity
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ProblemJson"
            application/json:
              examples:
                response:
                  value:
                    type: https://checkout.pagopa.it/problems/psp-violation
                    title: PSP Service Error
                    status: 422
                    detail: No PSP Service is available
        "500":
          description: generic error
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ProblemJson"
            application/json:
              examples:
                response:
                  value:
                    type: https://checkout.pagopa.it/problems/constraint-violation
                    title: Service Error
                    status: 500
                    detail: Generic Error
components:
  schemas:
    ProblemJson:
      type: object
      properties:
        type:
          type: string
          format: uri
          description: |-
            An absolute URI that identifies the problem type. When dereferenced,
            it SHOULD provide human-readable documentation for the problem type
            (e.g., using HTML).
          default: about:blank
          example: https://checkout.pagopa.it/problems/constraint-violation
        title:
          type: string
          description: >-
            A short, summary of the problem type. Written in english and
            readable

            for engineers (usually not suited for non technical stakeholders and

            not localized); example: Service Unavailable
        status:
          type: integer
          format: int32
          description: >-
            The HTTP status code generated by the origin server for this
            occurrence

            of the problem.
          minimum: 100
          maximum: 600
          exclusiveMaximum: true
          example: 400
        detail:
          type: string
          description: |-
            A human readable explanation specific to this occurrence of the
            problem.
          example: There was an error processing the request
        instance:
          type: string
          format: uri
          description: >-
            An absolute URI that identifies the specific occurrence of the
            problem.

            It may or may not yield further information if dereferenced.
    CartRequest:
      type: object
      required:
        - paymentNotices
        - returnUrls
      properties:
        emailNotice:
          type: string
          format: email
          example: my_email@mail.it
        paymentNotices:
          type: array
          items:
            $ref: "#/components/schemas/PaymentNotice"
          minItems: 1
          maxItems: 5
          example:
            - noticeNumber: "302012387654312384"
              fiscalCode: "77777777777"
              amount: 10000
              companyName: "companyName"
              description: "description"
            - noticeNumber: "302012387654312385"
              fiscalCode: "77777777777"
              amount: 5000
              companyName: "companyName"
              description: "description"
        returnUrls:
          type: object
          required:
            - returnOkUrl
            - returnCancelUrl
            - returnErrorUrl
          properties:
            returnOkUrl:
              type: string
              format: uri
              example: https://www.comune.di.prova.it/pagopa/success.html
            returnCancelUrl:
              type: string
              format: uri
              example: https://www.comune.di.prova.it/pagopa/cancel.html
            returnErrorUrl:
              type: string
              format: uri
              example: https://www.comune.di.prova.it/pagopa/error.html
    PaymentNotice:
      type: object
      required:
        - noticeNumber
        - fiscalCode
        - amount
        - companyName
        - description
      properties:
        noticeNumber:
          description: notice number 
          type: string
          minLength: 18
          maxLength: 18
        fiscalCode:
          description: Public Administration tax code
          type: string
          minLength: 11
          maxLength: 11
        amount:
          description: amount ( in euro cents ) of the payment notice  
          type: integer
          minimum: 1
        companyName:
          description: Public Administration company name
          type: string
          maxLength: 140
        description:
          description: subject of payment 
          type: string
          maxLength: 140
    CartResponse:
      type: object
      properties:
        idCart:
          type: string
          format: uuid
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        checkoutUrl:
          type: string
          format: uri
          example: https://checkout.pagopa.it/3fa85f64-5717-4562-b3fc-2c963f66afa6