openapi: 3.0.0
info:
  version: 0.0.1
  title: Pagopa Redirect
  description: >
    Collection of all api used for perform a transaction using redirect payment instrument.
    Api's are tagged as follow:
      * `b2b - PSP side` are implemented and exposed by PSP to expose api's  to p retrieve redirection URL and perform refund. For further information on connectivity, see [pagoPA connettivity](https://docs.pagopa.it/sanp/appendici/connettivita#nodo-dei-pagamenti-client).
      * `b2b - pagoPA side` are implemented and exposed by pagoPA to receive authorization outcome. For further information on connectivity, see [pagoPA connettivity](https://docs.pagopa.it/sanp/appendici/connettivita#nodo-dei-pagamenti-server).
  contact:
    name: pagoPA - Touchpoints team
tags:
  - name: b2b - PSP side
    description: Api's to initialize and refund a transaction
  - name: b2b - pagoPA side
    description: Api's to notify transaction outcome
servers:
  - url: https://${host}
externalDocs:
  url: https://docs.pagopa.it/sanp/prestatore-di-servizi-di-pagamento/modalita-di-integrazione/integrazione-per-strumento-di-pagamento-tramite-redirect
  description: SANP
paths:
  /redirections:
    post:
      externalDocs:
        url: https://docs.pagopa.it/sanp/prestatore-di-servizi-di-pagamento/modalita-di-integrazione/integrazione-per-strumento-di-pagamento-tramite-redirect#api-recupero-url
        description: Api recupero URL (SANP)
      tags:
        - b2b - PSP side
      operationId: RetrieveRedirectUrl
      summary: Retrieve redirect URL
      description: Retrieve redirect URL to be followed to perform transaction payment
      requestBody:
        $ref: '#/components/requestBodies/RedirectUrlRequest'
      responses:
        '200':
          description: Redirect url response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedirectUrlResponse'
        '400':
          description: Formally invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                status: 400
                detail: Bad request
                idTransaction: 3fa85f6457174562b3fc2c963f66afa6
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                status: 401
                detail: Unauthorized
                idTransaction: 3fa85f6457174562b3fc2c963f66afa6
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                status: 500
                detail: There was an error processing the request
                idTransaction: 3fa85f6457174562b3fc2c963f66afa6
  /redirections/refunds:
    post:
      externalDocs:
        url:  https://docs.pagopa.it/sanp/prestatore-di-servizi-di-pagamento/modalita-di-integrazione/integrazione-per-strumento-di-pagamento-tramite-redirect#api-annullo
        description: Api annullo (SANP)
      tags:
        - b2b - PSP side
      operationId: RefundTransaction
      summary: Api for refund
      description: |
        Perform a refund for a transaction. Semantically this endpoint is a DELETE with body (HTTP requests with the DELETE method should not have a body as per [RFC 9110, section 9.3.5, paragraph 5](https://www.rfc-editor.org/rfc/rfc9110#DELETE)).
      requestBody:
        $ref: '#/components/requestBodies/RefundRequest'

      responses:
        '200':
          description: Successful refund response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponse'
        '400':
          description: Formally invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                status: 400
                detail: Bad request
                idTransaction: 3fa85f6457174562b3fc2c963f66afa6
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                status: 401
                detail: Unauthorized
                idTransaction: 3fa85f6457174562b3fc2c963f66afa6
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                status: 404
                detail: Transaction not found
                idTransaction: 3fa85f6457174562b3fc2c963f66afa6
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                status: 500
                detail: There was an error processing the request
                idTransaction: 3fa85f6457174562b3fc2c963f66afa6
  /redirections/{idTransaction}/outcomes:
    post:
      externalDocs:
        url: https://docs.pagopa.it/sanp/prestatore-di-servizi-di-pagamento/modalita-di-integrazione/integrazione-per-strumento-di-pagamento-tramite-redirect#api-callback-esito-transazione
        description: Api callback esito transazione (SANP)
      tags:
        - b2b - pagoPA side
      operationId: CallbackOutcome
      summary: Callback API for communicate authorization outcome
      description: Communicate the outcome for the authorization process
      security:
        - PagopaApiKeyAuth: []
      parameters:
        - in: path
          name: idTransaction
          schema:
            $ref: '#/components/schemas/PagopaIdTransaction'
          required: true
          description: PagoPA unique identifier of the transaction to be refund (the same given in the redirections/url request)
      requestBody:
        $ref: '#/components/requestBodies/TransactionResultRequest'
      responses:
        '200':
          description: Outcome response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResultResponse'
        '400':
          description: Formally invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                status: 400
                detail: Bad request
                idTransaction: 3fa85f6457174562b3fc2c963f66afa6
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                status: 401
                detail: Unauthorized
                idTransaction: 3fa85f6457174562b3fc2c963f66afa6
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                status: 404
                detail: Transaction not found
                idTransaction: 3fa85f6457174562b3fc2c963f66afa6
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                status: 500
                detail: There was an error processing the request
                idTransaction: 3fa85f6457174562b3fc2c963f66afa6
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://example.com/problem/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:
          $ref: '#/components/schemas/HttpStatusCode'
        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.
        idTransaction:
          $ref: '#/components/schemas/PagopaIdTransaction'
    HttpStatusCode:
      type: integer
      format: int32
      description: |-
        The HTTP status code generated by the origin server for this occurrence
        of the problem.
      minimum: 400
      maximum: 600
      exclusiveMaximum: true
      example: 400
    RedirectUrlRequest:
      type: object
      description: Redirect URL request
      properties:
        idTransaction:
          $ref: '#/components/schemas/PagopaIdTransaction'
        idPsp:
          description: PSP identifier
          type: string
        amount:
          $ref: '#/components/schemas/AmountEuroCents'
        urlBack:
          description: pagoPA platform URL where redirect users after payment transaction have been completed
          type: string
          format: uri
        description:
          description: Payment description
          type: string
        idPaymentMethod:
          description: Redirect payment method type
          type: string
        touchpoint:
          description: Touchpoint used to initiate the transaction
          type: string
          enum:
            - CHECKOUT
            - IO
        paName:
          description: Name of the payment notice issuer
          type: string
          minLength: 1
          maxLength: 70
        paymentMethod:
          description: Description of the payment method chosen by the user
          type: string
        email:
          description: Email to which send the pagoPA payment receipt
          type: string
      required:
        - idTransaction
        - idPsp
        - amount
        - urlBack
        - description
        - idPaymentMethod
        - touchpoint
      example:
        idTransaction: 3fa85f6457174562b3fc2c963f66afa6
        idPsp: idPsp
        amount: 99999999
        urlBack: https://psp.site/payment
        description: payment description
        idPaymentMethod: RBPIC
        touchpoint: CHECKOUT
        paName: paName
        paymentMethod: Pago in Conto Intesa
    RedirectUrlResponse:
      description: Redirect URL response
      type: object
      properties:
        url:
          description: URL where user has to be redirect to start payment
          type: string
          format: url
        idTransaction:
          $ref: '#/components/schemas/PagopaIdTransaction'
        idPSPTransaction:
          description: Unique identifier for the payment operation PSP side
          type: string
        amount:
          $ref: '#/components/schemas/AmountEuroCents'
        timeout:
          description: Max time that pagoPA systems have to await for an outcome callback call. Any request received after this timeout will be discarded and transaction treated as for a missing callback call
          type: integer
          format: int32
          minimum: 0
          maximum: 600000
      required:
        - url
        - idTransaction
        - idPSPTransaction
        - amount
    RefundResponse:
      type: object
      description: Refund response body
      properties:
        idTransaction:
          $ref: '#/components/schemas/PagopaIdTransaction'
        outcome:
          $ref: '#/components/schemas/RefundOutcome'
      required:
        - idTransaction
        - outcome
    AmountEuroCents:
      description: Amount for payments, in euro cents
      type: integer
      format: int32
      minimum: 0
      maximum: 99999999
    PagopaIdTransaction:
      description: Uniquely identify a transaction
      type: string
      minLength: 32
      maxLength: 32
      example: 3fa85f6457174562b3fc2c963f66afa6
    RefundOutcome:
      description: |
        Refund operation outcome:
        it can be one of the following values:
        * OK - `Refund operation processed successfully`
        * KO - `There was an error performing refund`
        * CANCELED - `The transaction was already refunded`
      type: string
      enum:
        - OK
        - KO
        - CANCELED
    TransactionResultRequest:
      description: Callback api transaction outcome request body
      type: object
      properties:
        idPsp:
          type: string
          description: PSP identifier as received in redirections url request
        idPSPTransaction:
          type: string
          description: Unique PSP transaction identifier
        outcome:
          $ref: '#/components/schemas/AuthorizationOutcome'
        details:
          $ref: '#/components/schemas/TransactionResultDetails'
      required:
        - idPsp
        - idPSPTransaction
        - outcome
    TransactionResultDetails:
      type: object
      oneOf:
        - $ref: '#/components/schemas/TransactionAuthorizedOutcomeDetails'
        - $ref: '#/components/schemas/TransactionDeniedOutcomeDetails'
      discriminator:
        propertyName: outcome
        mapping:
          OK: '#/components/schemas/TransactionAuthorizedOutcomeDetails'
          KO: '#/components/schemas/TransactionDeniedOutcomeDetails'
          CANCELED: '#/components/schemas/TransactionDeniedOutcomeDetails'
          EXPIRED: '#/components/schemas/TransactionDeniedOutcomeDetails'
          ERROR: '#/components/schemas/TransactionDeniedOutcomeDetails'

    TransactionAuthorizedOutcomeDetails:
      type: object
      properties:
        timestampOperation:
          type: string
          format: date-time
          description: Payment date and time
        authorizationCode:
          type: string
          description: Unique PSP authorization code
      required:
        - timestampOperation
        - authorizationCode
    TransactionDeniedOutcomeDetails:
      type: object
      properties:
        errorCode:
          type: string
          description: Authorization error code
      required:
        - errorCode

    TransactionResultResponse:
      description: Callback api transaction outcome response body
      type: object
      properties:
        idTransaction:
          $ref: '#/components/schemas/PagopaIdTransaction'
        outcome:
          $ref: '#/components/schemas/AuthorizationResponseOutcome'
      required:
        - idTransaction
        - outcome
    AuthorizationOutcome:
      description: |
        Transaction outcome enumeration.
        The outcome can assume the following values:
        * OK -> `Authorization completed successfully`
        * KO -> `Authorization KO (for example missing funds for transaction)`
        * CANCELED -> `User canceled the authorization process`
        * EXPIRED -> `Authorization process has not been completed before timeout set for the operation`
        * ERROR -> `An unexpected error occurred during authorization process`
      type: string
      enum:
        - OK
        - KO
        - CANCELED
        - EXPIRED
        - ERROR
    AuthorizationResponseOutcome:
      description: |
        Transaction authorization callback process outcome.
        The outcome can assume the following values:
        * OK -> callback request have been processed successfully
        * KO -> there was an error processing the callback request
      type: string
      enum:
        - OK
        - KO
    RefundRequest:
      type: object
      properties:
        idTransaction:
          $ref: '#/components/schemas/PagopaIdTransaction'
        idPSPTransaction:
          description: PSP transaction id
          type: string
        action:
          description: Requested action (i.e. refund)
          type: string
      required:
        - idTransaction
        - idPSPTransaction
        - action
      example:
        idTransaction: 3fa85f6457174562b3fc2c963f66afa6
        idPSPTransaction: idPSPTransaction
        action: refund

  requestBodies:
    RedirectUrlRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RedirectUrlRequest'
          examples:
            Poste addebito in conto Retail (RBPR):
              value:
                idTransaction: 3fa85f6457174562b3fc2c963f66afa6
                idPsp: idPsp
                amount: 99999999
                urlBack: https://psp.site/payment
                description: payment description
                idPaymentMethod: RBPR
                touchpoint: CHECKOUT
                paName: paName
                paymentMethod: Poste addebito in conto Retail
            Poste addebito in conto Business (RBPB):
              value:
                idTransaction: 3fa85f6457174562b3fc2c963f66afa6
                idPsp: idPsp
                amount: 99999999
                urlBack: https://psp.site/payment
                description: payment description
                idPaymentMethod: RBPB
                touchpoint: CHECKOUT
                paName: paName
                paymentMethod: Poste addebito in conto Business
            Pago con BottonePostePay (RBPP):
              value:
                idTransaction: 3fa85f6457174562b3fc2c963f66afa6
                idPsp: idPsp
                amount: 99999999
                urlBack: https://psp.site/payment
                description: payment description
                idPaymentMethod: RBPP
                touchpoint: CHECKOUT
                paName: paName
                paymentMethod: Pago con BottonePostePay
            Pago in Conto Intesa (RBPIC):
              value:
                idTransaction: 3fa85f6457174562b3fc2c963f66afa6
                idPsp: idPsp
                amount: 99999999
                urlBack: https://psp.site/payment
                description: payment description
                idPaymentMethod: RBPIC
                touchpoint: CHECKOUT
                paName: paName
                paymentMethod: Pago in Conto Intesa
            SCRIGNO Internet Banking (RBPS):
              value:
                idTransaction: 3fa85f6457174562b3fc2c963f66afa6
                idPsp: idPsp
                amount: 99999999
                urlBack: https://psp.site/payment
                description: payment description
                idPaymentMethod: RBPS
                touchpoint: CHECKOUT
                paName: paName
                paymentMethod: SCRIGNO Internet Banking
    RefundRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RefundRequest'
    TransactionResultRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TransactionResultRequest'
          examples:
            authorization outcome OK:
              value:
                idPsp: idPsp
                idPSPTransaction: idPSPTransaction
                outcome: OK
                details:
                  timestampOperation: '2024-01-12T11:59:40.873Z'
                  authorizationCode: authorizationCode
            authorization outcome KO:
              value:
                idPsp: idPsp
                idPSPTransaction: idPSPTransaction
                outcome: OK
                details:
                  errorCode: errorCode

  securitySchemes:
    PagopaApiKeyAuth:
      type: apiKey
      in: header
      name: Ocp-Apim-Subscription-Key
      description: pagoPA api key