---
swagger: "2.0"
info:
  x-ibm-name: sibs-iban-tin-confirmation-stb-api
  title: IBAN TIN Confirmation
  version: 1.0.2
  description: Provide you with the possibility to confirm whether a pair of IBAN/TIN
    (Tax Identification Number) – in Portuguese IBAN/NIF – belongs to your client
    (answer is “yes” or “no”). It can also validate, additionally, if there’s a match
    between IBAN/TIN/Postal Code.
schemes:
- https
basePath: /
consumes:
- application/json
produces:
- application/json
securityDefinitions:
  x-ibm-client-id:
    type: apiKey
    in: header
    name: X-IBM-Client-Id
security:
- x-ibm-client-id: []
x-ibm-configuration:
  testable: true
  enforced: true
  phase: realized
paths:
  /{aspsp-cde}/v1/client-data/iban-tin-confirmation:
    post:
      responses:
        200:
          description: 200 OK
          schema:
            $ref: '#/definitions/IbanTinResponseResource'
        400:
          description: Bad Request.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
        401:
          description: Unauthorized.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
        403:
          description: Forbidden.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
        404:
          description: Not Found.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
        405:
          description: Method Not Allowed.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
        406:
          description: Not Acceptable.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
        408:
          description: Request Timeout.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
        415:
          description: Unsupported Media Type.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
        429:
          description: Too Many Requests.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
        500:
          description: Internal Server Error.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
        503:
          description: Service Unavailable.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
        504:
          description: Gatewaty Timeout.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
      tags:
      - Validation IBAN TIN
      summary: Validation IBAN TIN
      operationId: validationIbanTin
      description: Requests the validation of the correlation between IBAN and TIN.
      parameters:
      - $ref: '#/parameters/IbanTinValidationRequest'
      - $ref: '#/parameters/psuInvolved'
      - $ref: '#/parameters/aspsp-cde'
      - $ref: '#/parameters/TPP-Transaction-ID'
      - $ref: '#/parameters/TPP-Request-ID'
      - $ref: '#/parameters/PSU-Agent'
      - $ref: '#/parameters/PSU-IP-Address'
      - $ref: '#/parameters/PSU-Geo-Location'
      - $ref: '#/parameters/PSU-IP-Port'
      - $ref: '#/parameters/PSU-Device-ID'
      - $ref: '#/parameters/PSU-Device-Fingerprint'
      - $ref: '#/parameters/Digest'
  /{aspsp-cde}/v1/client-data/iban-tin-postalcode-confirmation:
    post:
      responses:
        200:
          description: 200 OK
          schema:
            $ref: '#/definitions/IbanTinPCResponseResource'
        400:
          description: Bad Request.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
        401:
          description: Unauthorized.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
        403:
          description: Forbidden.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
        404:
          description: Not Found.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
        405:
          description: Method Not Allowed.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
        406:
          description: Not Acceptable.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
        408:
          description: Request Timeout.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
        415:
          description: Unsupported Media Type.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
        429:
          description: Too Many Requests.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
        500:
          description: Internal Server Error.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
        503:
          description: Service Unavailable.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
        504:
          description: Gatewaty Timeout.
          headers:
            Location:
              type: string
              description: Response Location.
          schema:
            $ref: '#/definitions/ErrorMessageWithStatus'
      tags:
      - Get correlation between IBAN, TIN and Postal Code
      summary: Get correlation between IBAN, TIN and Postal Code
      operationId: validationIbanTinPostalCode
      description: Requests the validation of the correlation between IBAN, TIN and
        Postal Code.
      parameters:
      - $ref: '#/parameters/IbanTinPostalCodeValidationRequest'
      - $ref: '#/parameters/psuInvolved'
      - $ref: '#/parameters/aspsp-cde'
      - $ref: '#/parameters/TPP-Transaction-ID'
      - $ref: '#/parameters/TPP-Request-ID'
      - $ref: '#/parameters/PSU-Agent'
      - $ref: '#/parameters/PSU-IP-Address'
      - $ref: '#/parameters/PSU-Geo-Location'
      - $ref: '#/parameters/PSU-IP-Port'
      - $ref: '#/parameters/PSU-Device-ID'
      - $ref: '#/parameters/PSU-Device-Fingerprint'
      - $ref: '#/parameters/Digest'
definitions:
  AccountReference:
    description: Identifier of the addressed account.
    type: object
    properties:
      iban:
        description: International Bank Account Number
        type: string
        pattern: ^[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}$
        default: PT000
      bban:
        description: This data elements is used for payment accounts which have no
          IBAN.
        type: string
        default: "1"
        pattern: ^[a-zA-Z0-9]{1,30}$
      pan:
        description: Primary Account Number (PAN) of a card, can be tokenised by the
          ASPSP due to PCI DSS requirements.
        type: string
        maxLength: 35
        default: ""
      maskedPan:
        description: Primary Account Number (PAN) of a card in a masked form.
        type: string
        maxLength: 35
        default: ""
      msisdn:
        description: An alias to access a payment account via a registered mobile
          phone number
        type: string
        maxLength: 35
        default: ""
      currency:
        description: ISO 4217 Alpha 3 currency code.
        type: string
        default: ""
    additionalProperties: false
    required:
    - iban
  ErrorMessageWithStatus:
    description: Error and status Information.
    type: object
    properties:
      transactionStatus:
        $ref: '#/definitions/TransactionStatusType'
        description: The transaction status is filled with codes of the ISO 20022
          corresponding element.
      tppMessages:
        $ref: '#/definitions/TppMessageArray'
        description: Messages to the TPP on operational issues.
    additionalProperties: false
  IbanTinResponseResource:
    properties:
      transactionStatus:
        description: Status
        $ref: '#/definitions/TransactionStatusType'
      tinMatchIndicator:
        type: boolean
        description: Status of IBAN and TIN correlation validation.
      accountOwnershipCategory:
        type: string
        description: 'Only fulfilled if TinMatchIndicator is equal to "True". \n Account
          Ownership Category considered are: \n - Single Account; \n - Joint Account;
          \n - Solidary Account; \n - Mixed Account; \n - Business/Organisation Account;
          \n - Other Account Ownership Category. \n'
    additionalProperties: false
    required:
    - transactionStatus
    - tinMatchIndicator
  IbanTinPCResponseResource:
    properties:
      transactionStatus:
        description: Status
        $ref: '#/definitions/TransactionStatusType'
      tinMatchIndicator:
        type: boolean
        description: Status of IBAN and TIN correlation validation.
      postalCodeMatchIndicator:
        type: boolean
        description: Status of TIN and Postal Code correlation validation.
      accountOwnershipCategory:
        type: string
        description: 'Only fulfilled if TinMatchIndicator is equal to "True". \n Account
          Ownership Category considered are: \n - Single Account; \n - Joint Account;
          \n - Solidary Account; \n - Mixed Account; \n - Business/Organisation Account;
          \n - Other Account Ownership Category. \n'
    additionalProperties: false
    required:
    - transactionStatus
    - tinMatchIndicator
    - postalCodeMatchIndicator
  MessageCode:
    description: Message error codes.
    type: string
    enum:
    - SERVICE_BLOCKED
    - CORPORATE_ID_IVALID
    - CONSENT_UNKNOWN
    - CONSENT_INVALID
    - CONSENT_EXPIRED
    - RESOURCE_UNIKNOWN
    - RESOURCE_EXPIRED
    - TIMESTAMP_INVALID
    - PERIOD_INVALID
    - TRANSACTION_ID_INVALID
    - PRODUCT_INVALID
    - PRODUCT_UNKNOWN
    - REQUIRED_KID_MISSING
    - SESSIONS_NOT_SUPPORTED
    - ACCESS_EXCEEDED
    - REQUESTED_FORMATS_INVALID
    additionalProperties: false
  IbanTinValidationRequestResource:
    type: object
    properties:
      access:
        type: object
        properties:
          account:
            $ref: '#/definitions/AccountReference'
        description: Requested access services.
        required:
        - account
      taxpayerIdentificationNumber:
        type: string
        maxLength: 12
        default: ""
        description: Taxpayer Identification Number. It must be fulfilled with TIN
          Country Code followed by Taxpayer Identification Number.
      creditorAgent:
        description: BICFI - Identification of Creditor (BIC SWIFT). It must be fulfilled
          whenever IBAN do not begin with PT50.
        type: string
        pattern: ^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$
        default: ABCDEFABC0A
    required:
    - access
    - taxpayerIdentificationNumber
  IbanTinPostalCodeValidationRequestResource:
    type: object
    properties:
      access:
        type: object
        properties:
          account:
            $ref: '#/definitions/AccountReference'
        description: Requested access services.
      taxpayerIdentificationNumber:
        type: string
        maxLength: 12
        default: ""
        description: Taxpayer Identification Number. It must be fulfilled with TIN
          Country Code followed by Taxpayer Identification Number.
      postalCode:
        type: string
        maxLength: 4
        description: Client Address Postal Code. It should only fulfilled with the
          first 4 digits of Postal Code.
        pattern: ^\d{4}$
        default: "1111"
      creditorAgent:
        description: BICFI - Identification of Creditor (BIC SWIFT). It must be fulfilled
          whenever IBAN do not begin with PT50.
        type: string
        pattern: ^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$
        default: ABCDEFABC0A
    required:
    - access
    - taxpayerIdentificationNumber
    - postalCode
  TppMessage:
    required:
    - category
    - code
    description: Transports additional error information.
    properties:
      category:
        type: string
        default: ""
        description: Only ”ERROR” or "WARNING" permitted
      code:
        $ref: '#/definitions/MessageCode'
        description: Message error code.
      path:
        type: string
        default: ""
        description: Path of the element of the request message which provoked this
          error message.
      text:
        type: string
        maxLength: 512
        default: ""
        description: Additional explaining text.
    additionalProperties: false
  TppMessageArray:
    type: array
    description: Messages to the TPP on operational issues.
    items:
      $ref: '#/definitions/TppMessage'
      description: Transports additional error information.
  TransactionStatusType:
    description: |
      ISO20022: The transaction status is filled with value of the ISO20022 data table.
    type: string
    enum:
    - ACTC
    - RJCT
    default: RJCT
    additionalProperties: false
tags: []
parameters:
  aspsp-cde:
    name: aspsp-cde
    type: string
    required: true
    in: path
    description: Identification of the aspsp
  psuInvolved:
    name: psuInvolved
    type: boolean
    required: true
    in: query
    description: It must be contained if the PSU is involved in request process. This
      flag is then set to "true".
  Digest:
    name: Digest
    type: string
    required: false
    in: header
    description: Hash of the message body. Should be present when Request body exists
    default: ""
  PSU-Agent:
    name: PSU-Agent
    type: string
    required: false
    in: header
    description: It should be fulfilled whenever psuInvolved is set to "true". The
      forwarded Agent header field of the http request between PSU and TPP.
  PSU-Device-ID:
    name: PSU-Device-ID
    type: string
    required: false
    in: header
    description: It should be fulfilled whenever psuInvolved is set to "true". UUID
      (Universally Unique Identifier) for a device, which is used by the PSU, if available.  UUID
      identifies either a device or a device dependant application installation. In
      case of an installation identification this ID need to be unaltered until removal
      from device.
  PSU-Device-Fingerprint:
    name: PSU-Device-Fingerprint
    type: string
    required: false
    in: header
    description: It should be fulfilled whenever psuInvolved is set to "true". Fingerprint
      of the device used in the request between PSU and TPP, if available.
  PSU-IP-Address:
    name: PSU-IP-Address
    type: string
    required: false
    in: header
    description: It should be fulfilled whenever psuInvolved is set to "true". The
      forwarded IP Address header field consists of the corresponding http request
      IP Address field between PSU and TPP.
  PSU-IP-Port:
    name: PSU-IP-Port
    type: string
    required: false
    in: header
    description: It should be fulfilled whenever psuInvolved is set to "true". The
      forwarded IP Port header field consists of the corresponding HTTP request IP
      Port field between PSU and TPP, if available.
  PSU-Geo-Location:
    name: PSU-Geo-Location
    type: string
    required: false
    in: header
    description: It should be fulfilled whenever psuInvolved is set to "true". The
      forwarded Geo Location of the corresponding http request between PSU and TPP
      if available.
  IbanTinValidationRequest:
    name: IbanTinValidationRequest
    required: true
    in: body
    schema:
      $ref: '#/definitions/IbanTinValidationRequestResource'
    description: Is asking for detailed account information.
  IbanTinPostalCodeValidationRequest:
    name: IbanTinPostalCodeValidationRequest
    required: true
    in: body
    schema:
      $ref: '#/definitions/IbanTinPostalCodeValidationRequestResource'
    description: ""
  TPP-Request-ID:
    name: TPP-Request-ID
    type: string
    required: true
    in: header
    description: ID of the request, unique to the call, as determined by the initiating
      party.
  TPP-Transaction-ID:
    name: TPP-Transaction-ID
    type: string
    required: true
    in: header
    description: ID of the transaction as determined by the initiating party.
x-ibm-endpoints:
- endpointUrl: https://site2.sibsapimarket.com:8445/sibs/apimarket-sb
  type:
  - production
  - development
- endpointUrl: https://site1.sibsapimarket.com:8445/sibs/apimarket-sb
  type:
  - production
  - development
...