Spotnana Personal Payment Sources API

openapi: 3.1.0
info:
  title: Air Personal Payment Sources API
  version: v2
  description: APIs to perform search, checkout and book an air pnr
servers:
- url: https://api-ext-sboxmeta.partners.spotnana.com
  description: Sandbox URL
security:
- Bearer: []
tags:
- name: Personal Payment Sources
paths:
  /v2/payment/users/{userId}/payment-sources:
    description: 'API to Create Personal Payment Source

      '
    parameters:
    - name: userId
      in: path
      description: Identifier for User Profile
      required: true
      schema:
        type: string
        format: uuid
      example: 4974a66b-7493-4f41-908c-58ba81093947
    get:
      tags:
      - Personal Payment Sources
      summary: List personal payment sources for a User
      operationId: listUserPaymentSources
      parameters:
      - name: offset
        in: query
        description: Indicates from where in the list of Payment Sources the server should start.
        schema:
          type: integer
          default: 0
          minimum: 0
      - name: limit
        in: query
        description: Maximum number of results to be fetched for the query.
        schema:
          type: integer
          default: 10
          minimum: 0
          maximum: 10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPaymentSourceResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      tags:
      - Personal Payment Sources
      summary: Create Personal Payment Source.
      operationId: createPersonalPaymentSource
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentSourceRequestV2'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePaymentSourceResponseV2'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/payment/users/{userId}/payment-sources/{paymentSourceId}:
    description: 'APIs to Read, Update and Delete Personal Payment Source

      '
    parameters:
    - name: userId
      in: path
      description: Identifier for User Profile
      required: true
      schema:
        type: string
        format: uuid
      example: 4974a66b-7493-4f41-908c-58ba81093947
    - name: paymentSourceId
      in: path
      description: Identifier for personal paymentSource.
      required: true
      schema:
        type: string
        format: uuid
      example: 4974a66b-7493-4f41-908c-58ba81093947
    get:
      tags:
      - Personal Payment Sources
      summary: Fetch a personal payment source
      operationId: getPersonalPaymentSource
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPaymentSourceResponseV2'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Personal Payment Sources
      summary: Delete a Personal Payment Source.
      operationId: deletePersonalPaymentSource
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Personal Payment Sources
      summary: Update a Personal Payment Source.
      operationId: updatePersonalPaymentSource
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePersonalPaymentSourceRequest'
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The specified resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    OffsetBasedPaginationResponseParams:
      type: object
      title: PaginationResponseParams
      description: Pagination parameters for response.
      required:
      - totalNumResults
      properties:
        totalNumResults:
          type: integer
          format: int32
          description: Total number of results.
    CreatePaymentSourceRequestV2:
      type: object
      title: CreatePaymentSourceRequestV2
      description: Represents the request payload to create a new payment source.
      required:
      - paymentSourceInfo
      properties:
        paymentSourceInfo:
          description: Detailed information about the payment source to be created.
          $ref: '#/components/schemas/PaymentSourceInfoV2'
    TMCPaymentFilter:
      type: object
      title: TMCPaymentFilter
      description: Defines filter specific to tmc payment sources.
      required:
      - type
      properties:
        type:
          type: string
          example: TMC
    PaymentSourceDetails:
      type: object
      title: PaymentSourceDetails
      description: Contains details about a payment source, including its type and specific attributes.
      discriminator:
        propertyName: type
        mapping:
          CARD: '#/components/schemas/CardPaymentSource'
      oneOf:
      - $ref: '#/components/schemas/CardPaymentSource'
    CardPaymentSourceUpdate:
      type: object
      title: CardPaymentSourceUpdate
      description: This describes the details for a card payment source.
      required:
      - paymentType
      - card
      properties:
        paymentType:
          type: string
          example: CARD
        card:
          $ref: '#/components/schemas/CardUpdate'
    PaymentSourceUpdateDetails:
      type: object
      title: PaymentSourceUpdateDetails
      description: Specifies the details required to update an existing payment source.
      discriminator:
        propertyName: paymentType
        mapping:
          CARD: '#/components/schemas/CardPaymentSourceUpdate'
      oneOf:
      - $ref: '#/components/schemas/CardPaymentSourceUpdate'
    CardUpdate:
      type: object
      title: CardUpdate
      description: Card Details to be updated
      properties:
        address:
          description: Billing address
          $ref: '#/components/schemas/PostalAddress'
        label:
          type: string
          description: Card Label
          example: Label amex
        ownershipLabel:
          $ref: '#/components/schemas/OwnershipLabel'
    TravelType:
      type: string
      title: TravelType
      description: Travel Type
      enum:
      - AIR
      - HOTEL
      - CAR
      - RAIL
      - LIMO
      - MISC
      - ALL
      example: AIR
    UpdatePersonalPaymentSourceRequest:
      type: object
      title: UpdatePersonalPaymentSourceRequest
      description: Request payload for updating an existing personal payment source.
      required:
      - paymentSourceInfo
      properties:
        paymentSourceInfo:
          description: Details of the payment source to be updated
          $ref: '#/components/schemas/PaymentSourceUpdateDetails'
        filter:
          description: Applicable Filters i.e. access level, travel type information etc.
          $ref: '#/components/schemas/UsagePaymentFilter'
    OwnershipLabel:
      title: OwnershipLabel
      type: string
      description: Ownership label of the card whether it is personal, corporate or central.
      enum:
      - CORPORATE
      - PERSONAL
      - CENTRAL
    CardPaymentSource:
      type: object
      title: CardPaymentSource
      description: Represents payment source details for a credit card.
      required:
      - type
      - card
      properties:
        type:
          type: string
          example: CARD
        card:
          $ref: '#/components/schemas/CardV2'
    Latlng:
      title: Latlng
      description: Latitude and Longitude for a Location
      type: object
      required:
      - latitude
      - longitude
      properties:
        latitude:
          type: number
          description: Latitude of the Location
          format: double
          example: 77.1025
        longitude:
          type: number
          description: Longitude of the Location
          format: double
          example: 28.7041
    UsagePaymentFilter:
      type: object
      title: UsagePaymentFilter
      description: Defines usage restrictions or filters for a payment source.
      discriminator:
        propertyName: type
        mapping:
          PERSONAL: '#/components/schemas/PersonalPaymentFilter'
          TMC: '#/components/schemas/TMCPaymentFilter'
      oneOf:
      - $ref: '#/components/schemas/PersonalPaymentFilter'
      - $ref: '#/components/schemas/TMCPaymentFilter'
      x-ignoreBreakingChanges:
      - UsagePaymentFilter->TMCPaymentFilter
    ManagedTravelerPaymentAccess:
      type: object
      description: Settings for sharing this payment method with managed traveler profiles. Applicable for Arranger Roles.
      required:
      - enabled
      properties:
        enabled:
          type: boolean
          description: Indicates if this payment method can be used on the Traveler Profiles being managed by this User.
          default: false
        visibility:
          type: object
          description: Controls how this payment method is displayed on checkout for managed traveler profiles, applicable only if sharing is enabled.
          properties:
            showToTravelers:
              type: boolean
              description: If true, managed travelers can see this payment method when booking for themselves. If false, only the Travel Arranger can see it.
              default: false
    ListPaymentSourceResponse:
      type: object
      title: ListPaymentSourceResponse
      description: Response containing a list of payment sources along with pagination details.
      properties:
        paymentSourceInfos:
          type: array
          description: List of payment sources
          items:
            $ref: '#/components/schemas/PaymentSourceInfoV2'
        paginationParams:
          $ref: '#/components/schemas/OffsetBasedPaginationResponseParams'
    AuthenticationInfo:
      type: object
      title: AuthenticationInfo
      description: Provides authentication details, such as URLs for 3DS.
      properties:
        authUrl:
          type: string
          description: URL provided by the payment gateway for completing authentication.
    GetPaymentSourceResponseV2:
      type: object
      title: GetPaymentSourceResponseV2
      description: Response returned when fetching details of a payment source.
      properties:
        paymentSource:
          description: Details of the payment source
          $ref: '#/components/schemas/PaymentSourceInfoV2'
    ErrorResponse:
      type: object
      properties:
        debugIdentifier:
          type: string
          description: Link to debug the error internally.
        errorMessages:
          type: array
          items:
            type: object
            properties:
              errorCode:
                type: string
                description: Error code to identify the specific errors.
              message:
                type: string
                description: Message containing details of error.
              errorParameters:
                type: array
                description: Error message parameters.
                items:
                  $ref: '#/components/schemas/ErrorParameter'
              errorDetail:
                type: string
                description: More details about the error.
    PostalAddress:
      title: PostalAddress
      description: Postal Address Details
      type: object
      required:
      - addressLines
      - regionCode
      properties:
        addressLines:
          description: Address lines
          type: array
          items:
            type: string
            example: Golden Gate Bridge
        administrativeArea:
          type: string
          description: 'Code of administrative area. For example: DL for Delhi, India.

            Highest administrative subdivision which is used for postal

            addresses of a country or region.

            For example, this can be a state, a province, an oblast, or a prefecture.

            Specifically, for Spain this is the province and not the autonomous

            community (e.g. "Barcelona" and not "Catalonia").

            Many countries don''t use an administrative area in postal addresses. E.g.

            in Switzerland this should be left unpopulated.

            '
          example: CA
        administrativeAreaName:
          type: string
          description: "Name of administrative area. This is full name corresponding to administrativeArea. \nLike Delhi for DL area code. For some places, code and name maybe same as well like Tokyo.\n"
          example: California
        description:
          description: Address description
          type: string
          example: San Francisco Home
        isDefault:
          description: Whether this address is default address in case multiple addresses are specified.
          type: boolean
          example: true
        languageCode:
          description: "BCP-47 language code of the contents of this address (if known). This is often the UI \nlanguage of the input form or is expected to match one of the languages used in the \naddress' country/region, or their transliterated equivalents.\nThis can affect formatting in certain countries, but is not critical to the correctness \nof the data and will never affect any validation or other non-formatting related operations.\nExamples: \"zh-Hant\", \"ja\", \"ja-Latn\", \"en\".\n"
          type: string
          example: en
        locality:
          description: Generally refers to the city/town portion of the address.
          type: string
          example: San Francisco
        locationCode:
          description: IATA 3-letter location code. See https://www.iata.org/en/services/codes.
          type: string
          example: LAX
        organization:
          description: The name of the organization at the address.
          type: string
          example: Spotnana
        postalCode:
          description: Postal code of the address. This is a required field when setting for a user/legal entity/company etc.
          type: string
          example: '94130'
        continentCode:
          description: 2 letter continent code of the continent this address falls in.
          type: string
          example: AF
        recipients:
          description: The recipient at the address.
          type: array
          items:
            type: string
        regionCode:
          description: Region code of the country/region of the address.
          type: string
          example: US
        regionName:
          description: Region name of the country/region of the address.
          type: string
          example: America
        revision:
          type: integer
          format: int32
          example: 1
        sortingCode:
          description: 'Additional, country-specific, sorting code. This is not used

            in most regions. Where it is used, the value is either a string like

            "CEDEX", optionally followed by a number (e.g. "CEDEX 7"), or just a number

            alone, representing the "sector code" (Jamaica), "delivery area indicator"

            (Malawi) or "post office indicator" (e.g. Côte d''Ivoire).

            '
          type: string
          example: Jamaica
        sublocality:
          description: Sublocality of the address. This can be neighborhoods, boroughs, districts.
          type: string
        timezone:
          description: Time zone of the address.
          type: string
          example: America/Los_Angeles
        coordinates:
          description: Map coordinates of the address.
          $ref: '#/components/schemas/Latlng'
    ErrorParameter:
      type: object
      title: ErrorParameter
      description: Error parameter
      properties:
        name:
          type: string
          description: Parameter name
        value:
          type: string
          description: Parameter value
    PaymentSourceStatus:
      type: string
      description: Status of the Payment Source.
      readOnly: true
      enum:
      - ACTIVE
      - INCOMPLETE
      - TEMPORARY_READY
      - TEMPORARY_USED
      - TEMPORARY_EXPIRED
      - TEMPORARY_INCOMPLETE
      x-ignoreBreakingChanges:
      - PaymentSourceStatus->TEMPORARY_READY
      - PaymentSourceStatus->TEMPORARY_USED
      - PaymentSourceStatus->TEMPORARY_EXPIRED
      - PaymentSourceStatus->TEMPORARY_INCOMPLETE
    CardCompany:
      type: string
      enum:
      - NONE
      - VISA
      - MASTERCARD
      - AMEX
      - DISCOVER
      - AIR_TRAVEL_UATP
      - CARTE_BLANCHE
      - DINERS_CLUB
      - JCB
      - BREX
      - UNION_PAY
      - EURO_CARD
      - ACCESS_CARD
      - ELO_CARD
      description: The issuing company of card
      example: VISA
    CardV2:
      type: object
      title: CardV2
      description: Card Details
      required:
      - company
      - name
      - address
      - number
      - label
      - expiry
      properties:
        company:
          $ref: '#/components/schemas/CardCompany'
        name:
          description: Name on card
          type: string
          example: Harrison Schwartz
          x-pii: SENSITIVE
        address:
          description: Billing address
          $ref: '#/components/schemas/PostalAddress'
          x-pii: SENSITIVE
        number:
          type: string
          description: Card number
          example: '4111111111111111'
        cvv:
          type: string
          description: Card cvv number
          example: '012'
        label:
          type: string
          description: Card Label
          example: Label amex
        expiry:
          description: Card Expiry.
          $ref: '#/components/schemas/Expiry'
        ownershipLabel:
          $ref: '#/components/schemas/OwnershipLabel'
          example: PERSONAL
    CreatePaymentSourceResponseV2:
      type: object
      title: CreatePaymentSourceResponseV2
      description: Response returned upon creating a payment source.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier identifying the created payment source, if created.
          example: f49d00fe-1eda-4304-ba79-a980f565281d
        status:
          $ref: '#/components/schemas/PaymentSourceStatus'
          description: Current status of the payment source.
        authenticationInfo:
          $ref: '#/components/schemas/AuthenticationInfo'
          description: Information required for additional authentication steps, such as 3D Secure verification.
    PersonalPaymentFilter:
      type: object
      title: PersonalPaymentFilter
      description: Defines filter specific to personal payment sources.
      required:
      - type
      - travelTypes
      properties:
        type:
          type: string
          example: PERSONAL
        travelTypes:
          type: array
          description: Applicable payment source travel types
          items:
            $ref: '#/components/schemas/TravelType'
          minItems: 1
          maxItems: 6
        managedTravelerAccess:
          description: Config for providing the access to Managed Travelers if any.
          $ref: '#/components/schemas/ManagedTravelerPaymentAccess'
    PaymentSourceInfoV2:
      type: object
      title: PaymentSourceInfoV2
      required:
      - paymentSource
      - filter
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier identifying the created payment source, if created.
          readOnly: true
        paymentSource:
          description: Details of the payment source
          $ref: '#/components/schemas/PaymentSourceDetails'
        filter:
          description: Applicable Filters i.e. access level, travel type information etc.
          $ref: '#/components/schemas/UsagePaymentFilter'
        status:
          readOnly: true
          description: Status of the payment source after creation. Only Active sources can be used for bookings.
          $ref: '#/components/schemas/PaymentSourceStatus'
        externalId:
          type: string
          description: An identifier assigned by a partner system. Once attached to a payment source, it remains unique per user and cannot be reassigned to another payment source.
          example: bxt_RNGsNfzgJDaTstKIKqK4xEuhGYAnMdYK8T40
    Expiry:
      title: Expiry
      type: object
      description: Contains the expiry of a Card.
      required:
      - expiryMonth
      - expiryYear
      properties:
        expiryMonth:
          type: integer
          format: int32
          minimum: 1
          maximum: 12
          description: Expiry month
          example: 1
        expiryYear:
          type: integer
          format: int32
          description: Expiry year
          minimum: 2000
          example: 2010
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer