openapi: 3.0.1
info:
  title: Token Vault service API
  description: >-
    This is an API reference for the Token Vault service, which provides
    endpoints to create and manage tokens and related cryptographic data.
  version: 1.0.0
servers:
  - url: https://api-services.pxp.io/api/v1
    description: Production environment
  - url: https://api-services.test.pxp.io/api/v1
    description: Sandbox environment
paths:
  /token-vault/{ownerType}/{ownerId}/vaults/gateway-tokens:
    post:
      summary: Create gateway token
      description: >-
        Request to create a gateway token, which is used to represent sensitive
        payment data in a secure and tokenised form.
      operationId: create-gateway-token
      parameters:
        - $ref: '#/components/parameters/ownerId'
        - $ref: '#/components/parameters/ownerType'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - primaryAccountNumber
                - expiryMonth
                - expiryYear
                - holderName
              type: object
              properties:
                primaryAccountNumber:
                  $ref: '#/components/schemas/primaryAccountNumber'
                expiryMonth:
                  $ref: '#/components/schemas/expiryMonth'
                expiryYear:
                  $ref: '#/components/schemas/expiryYear'
                cardVerificationCode:
                  $ref: '#/components/schemas/cardVerificationCode'
                holderName:
                  $ref: '#/components/schemas/holderName'
              additionalProperties: false
      responses:
        '200':
          description: Successful creation of the gateway token
          content:
            application/json:
              schema:
                type: object
                properties:
                  gatewayTokenId:
                    $ref: '#/components/schemas/gatewayTokenId'
                  maskedPrimaryAccountNumber:
                    $ref: '#/components/schemas/maskedPrimaryAccountNumber'
                  fundingSource:
                    $ref: '#/components/schemas/fundingSource'
                additionalProperties: false
              examples:
                Create Gateway Token Response:
                  value:
                    gatewayTokenId: 7f46c09d-d1d1-4f94-9a88-6e8ac32e6341
                    maskedPrimaryAccountNumber: 123456******7890
                    fundingSource: Credit
        '400':
          description: Bad request due to invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorised access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity due to semantic errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    $ref: '#/components/schemas/correlationId'
                  details:
                    $ref: '#/components/schemas/details'
                  errorCode:
                    $ref: '#/components/schemas/errorCode'
                  errorReason:
                    $ref: '#/components/schemas/errorReason'
  /token-vault/{ownerType}/{ownerId}/vaults/scheme-tokens:
    post:
      summary: Create scheme token
      description: >-
        Request to create a scheme token, representing payment data according to
        scheme rules.
      operationId: create-scheme-token
      parameters:
        - $ref: '#/components/parameters/ownerId'
        - $ref: '#/components/parameters/ownerType'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - primaryAccountNumber
                - expiryMonth
                - expiryYear
                - holderName
              type: object
              properties:
                primaryAccountNumber:
                  $ref: '#/components/schemas/primaryAccountNumber'
                expiryMonth:
                  $ref: '#/components/schemas/expiryMonth'
                expiryYear:
                  $ref: '#/components/schemas/expiryYear'
                cardVerificationCode:
                  $ref: '#/components/schemas/cardVerificationCode'
                holderName:
                  $ref: '#/components/schemas/holderName'
              additionalProperties: false
      responses:
        '200':
          description: Successful creation of the scheme token
          content:
            application/json:
              schema:
                type: object
                properties:
                  schemeTokenId:
                    description: >-
                      The unique scheme token ID generated by PXP. It is used as
                      a reference to extract the `schemeTokenNumber`.
                    type: string
                    format: uuid
                  fundingSource:
                    $ref: '#/components/schemas/fundingSource'
                additionalProperties: false
              examples:
                Create Scheme Token Response:
                  value:
                    schemeTokenId: 7d87f401-6977-43a4-8e72-8ff457fc8633
                    fundingSource: Bank Account
        '400':
          description: Bad request due to invalid input
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    $ref: '#/components/schemas/correlationId'
                  details:
                    $ref: '#/components/schemas/details'
                  errorCode:
                    type: string
                    description: The error code returned for the operation.
                    example: INVALID_REQUEST
                  errorReason:
                    type: string
                    description: The error reason returned for the operation.
                    example: The request parameters are invalid.
        '401':
          description: Unauthorised access
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    $ref: '#/components/schemas/correlationId'
                  details:
                    $ref: '#/components/schemas/details'
                  errorCode:
                    type: string
                    description: The error code returned for the operation.
                    example: INVALID_REQUEST
                  errorReason:
                    type: string
                    description: The error reason returned for the operation.
                    example: The request parameters are invalid.
        '403':
          description: Forbidden access
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    $ref: '#/components/schemas/correlationId'
                  details:
                    $ref: '#/components/schemas/details'
                  errorCode:
                    type: string
                    description: The error code returned for the operation.
                    example: INVALID_REQUEST
                  errorReason:
                    type: string
                    description: The error reason returned for the operation.
                    example: The request parameters are invalid.
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    $ref: '#/components/schemas/correlationId'
                  details:
                    $ref: '#/components/schemas/details'
                  errorCode:
                    type: string
                    description: The error code returned for the operation.
                    example: INVALID_REQUEST
                  errorReason:
                    type: string
                    description: The error reason returned for the operation.
                    example: The request parameters are invalid.
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    $ref: '#/components/schemas/correlationId'
                  details:
                    $ref: '#/components/schemas/details'
                  errorCode:
                    type: string
                    description: The error code returned for the operation.
                    example: INVALID_REQUEST
                  errorReason:
                    type: string
                    description: The error reason returned for the operation.
                    example: The request parameters are invalid.
        '422':
          description: Unprocessable entity due to semantic errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    $ref: '#/components/schemas/correlationId'
                  details:
                    $ref: '#/components/schemas/details'
                  errorCode:
                    type: string
                    description: The error code returned for the operation.
                    example: INVALID_REQUEST
                  errorReason:
                    type: string
                    description: The error reason returned for the operation.
                    example: The request parameters are invalid.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    $ref: '#/components/schemas/correlationId'
                  details:
                    $ref: '#/components/schemas/details'
                  errorCode:
                    type: string
                    description: The error code returned for the operation.
                    example: INVALID_REQUEST
                  errorReason:
                    type: string
                    description: The error reason returned for the operation.
                    example: The request parameters are invalid.
  /token-vault/{ownerType}/{ownerId}/vaults/scheme-tokens/{schemeTokenId}:
    get:
      summary: Get scheme token
      description: Request to get a scheme token and its status
      operationId: get-scheme-token
      parameters:
        - $ref: '#/components/parameters/ownerId'
        - $ref: '#/components/parameters/ownerType'
        - $ref: '#/components/parameters/schemeTokenId'
      responses:
        '200':
          description: Successful retrieval of the scheme token
          content:
            application/json:
              schema:
                type: object
                properties:
                  schemeTokenId:
                    type: string
                    format: uuid
                    description: >-
                      The unique scheme token ID generated by PXP. It is used as
                      a reference to extract the schemeTokenNumber.
                  schemeTokenProvider:
                    type: string
                    description: The name of the scheme token provider.
                  schemeTokenProcurementState:
                    type: string
                    description: The procurement state of the scheme token.
                  externalschemeTokenId:
                    type: string
                    nullable: true
                    description: >-
                      A unique identifier token provided by the external payment
                      scheme. This token allows merchants to process payments
                      through different payment service providers (PSPs) or
                      transaction service providers (TSPs). The token
                      facilitates interoperability between different PSPs,
                      enabling merchants to seamlessly integrate with and use
                      various payment processing services.
                  status:
                    type: string
                    nullable: true
                    description: The status of the scheme token.
                  paymentAccountReference:
                    type: string
                    nullable: true
                    description: >-
                      The payment account reference associated with the scheme
                      token.
                  schemeTokenNumber:
                    type: string
                    nullable: true
                    description: >-
                      The scheme token number represents a scheme token issued
                      by Visa or Mastercard, used for subsequent transaction
                      processing. This token enhances security and facilitates
                      recurring transactions, providing a secure and efficient
                      alternative to sharing sensitive card details.
                  expiryMonth:
                    $ref: '#/components/schemas/expiryMonth'
                  expiryYear:
                    $ref: '#/components/schemas/expiryYear'
              examples:
                Get Scheme Token Response:
                  value:
                    schemeTokenId: f47ac10b-58cc-4372-a567-0e02b2c3d479
                    schemeTokenProvider: Visa
                    schemeTokenProcurementState: Completed
                    externalschemeTokenId: ext-123456789
                    status: Active
                    paymentAccountReference: acc-987654321
                    schemeTokenNumber: '1234567812345678'
                    expiryMonth: '12'
                    expiryYear: '2025'
        '400':
          description: Bad request due to invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorised access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    type: string
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details:
                    $ref: '#/components/schemas/details'
                  errorCode:
                    $ref: '#/components/schemas/errorCode'
                  errorReason:
                    $ref: '#/components/schemas/errorReason'
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    type: string
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details:
                    $ref: '#/components/schemas/details'
                  errorCode:
                    $ref: '#/components/schemas/errorCode'
                  errorReason:
                    $ref: '#/components/schemas/errorReason'
        '422':
          description: Unprocessable entity due to semantic errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    type: string
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details:
                    $ref: '#/components/schemas/details'
                  errorCode:
                    $ref: '#/components/schemas/errorCode'
                  errorReason:
                    $ref: '#/components/schemas/errorReason'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    type: string
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details:
                    $ref: '#/components/schemas/details'
                  errorCode:
                    $ref: '#/components/schemas/errorCode'
                  errorReason:
                    $ref: '#/components/schemas/errorReason'
  /token-vault/{ownerType}/{ownerId}/vaults/scheme-tokens/{schemeTokenId}/cryptograms:
    post:
      summary: Create scheme token cryptogram
      description: >-
        Request to create a scheme token cryptogram, a secure cryptographic
        representation of the token.
      operationId: create-scheme-token-cryptogram
      parameters:
        - $ref: '#/components/parameters/ownerId'
        - $ref: '#/components/parameters/ownerType'
        - $ref: '#/components/parameters/schemeTokenId'
      responses:
        '200':
          description: Successful creation of the cryptogram
          content:
            application/json:
              schema:
                type: object
                properties:
                  schemeTokenCryptogram:
                    $ref: '#/components/schemas/schemeTokenCryptogram'
                  schemeTokenNumber:
                    description: >-
                      The scheme token number represents a scheme token issued
                      by Visa or Mastercard, used for subsequent transaction
                      processing. This token enhances security and facilitates
                      recurring transactions, providing a secure and efficient
                      alternative to sharing sensitive card details.
                    type: string
                    example: '4837261112345678'
                  cryptogramType:
                    description: The type of cryptogram (e.g., 3DSecure).
                    type: string
                    example: 3DSecure
                    nullable: true
                  clientPaymentDataId:
                    description: >-
                      The client payment data identifier associated with the
                      cryptogram.
                    type: string
                    nullable: true
                    example: abc123
                additionalProperties: false
              examples:
                Create Cryptogram Response:
                  value:
                    cryptogramType: 3DSecure
                    clientPaymentDataId: abc123
                    schemeTokenCryptogram: E1F53135E559C253
                    schemeTokenNumber: '4837261112345678'
        '400':
          description: Bad request due to invalid input
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    type: string
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details:
                    $ref: '#/components/schemas/details'
                  errorCode:
                    type: string
                    description: The error code returned for the operation.
                    example: INVALID_REQUEST
                  errorReason:
                    type: string
                    description: The error reason returned for the operation.
                    example: The request parameters are invalid.
        '401':
          description: Unauthorised access
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    type: string
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details:
                    $ref: '#/components/schemas/details'
                  errorCode:
                    type: string
                    description: The error code returned for the operation.
                    example: INVALID_REQUEST
                  errorReason:
                    type: string
                    description: The error reason returned for the operation.
                    example: The request parameters are invalid.
        '403':
          description: Forbidden access
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    type: string
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details:
                    $ref: '#/components/schemas/details'
                  errorCode:
                    type: string
                    description: The error code returned for the operation.
                    example: INVALID_REQUEST
                  errorReason:
                    type: string
                    description: The error reason returned for the operation.
                    example: The request parameters are invalid.
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    type: string
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details:
                    $ref: '#/components/schemas/details'
                  errorCode:
                    type: string
                    description: The error code returned for the operation.
                    example: INVALID_REQUEST
                  errorReason:
                    type: string
                    description: The error reason returned for the operation.
                    example: The request parameters are invalid.
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    type: string
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details:
                    $ref: '#/components/schemas/details'
                  errorCode:
                    type: string
                    description: The error code returned for the operation.
                    example: INVALID_REQUEST
                  errorReason:
                    type: string
                    description: The error reason returned for the operation.
                    example: The request parameters are invalid.
        '422':
          description: Unprocessable entity due to semantic errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    type: string
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details:
                    $ref: '#/components/schemas/details'
                  errorCode:
                    type: string
                    description: The error code returned for the operation.
                    example: INVALID_REQUEST
                  errorReason:
                    type: string
                    description: The error reason returned for the operation.
                    example: The request parameters are invalid.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    type: string
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details:
                    $ref: '#/components/schemas/details'
                  errorCode:
                    type: string
                    description: The error code returned for the operation.
                    example: INVALID_REQUEST
                  errorReason:
                    type: string
                    description: The error reason returned for the operation.
                    example: The request parameters are invalid.
  /token-vault/{ownerType}/{ownerId}/vaults/gateway-tokens/{gatewayTokenId}/card-data:
    get:
      summary: Get masked card data related to gateway token
      description: >-
        Request to get card data related to the gateway token. The returned
        sensitive data is unencrypted but masked to ensure security.
      operationId: get-masked-card-related-to-gateway-token
      parameters:
        - $ref: '#/components/parameters/ownerId'
        - $ref: '#/components/parameters/ownerType'
        - $ref: '#/components/parameters/gatewayTokenId'
      responses:
        '200':
          description: Successful retrieval of masked card data
          content:
            application/json:
              schema:
                type: object
                properties:
                  maskedPrimaryAccountNumber:
                    $ref: '#/components/schemas/maskedPrimaryAccountNumber'
                  expiryMonth:
                    $ref: '#/components/schemas/expiryMonth'
                  expiryYear:
                    $ref: '#/components/schemas/expiryYear'
                  holderName:
                    $ref: '#/components/schemas/holderName'
                  fundingSource:
                    $ref: '#/components/schemas/fundingSource'
                additionalProperties: false
              examples:
                Get gateway token card data response:
                  value:
                    maskedPrimaryAccountNumber: 123456******7890
                    expiryMonth: '12'
                    expiryYear: '2025'
                    holderName: Mr John Doe
                    fundingSource: Credit
        '400':
          description: Bad request due to invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorised access
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    $ref: '#/components/schemas/correlationId'
                  details:
                    $ref: '#/components/schemas/details'
                  errorCode:
                    $ref: '#/components/schemas/errorCode'
                  errorReason:
                    $ref: '#/components/schemas/errorReason'
        '403':
          description: Forbidden access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity due to semantic errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /token-vault/{ownerType}/{ownerId}/vaults/gateway-tokens/{gatewayTokenId}/card-data/encrypted:
    get:
      summary: Get encrypted card data related to gateway token
      description: >-
        Request to get card data related to the gateway token. The returned
        sensitive data is encrypted for enhanced security.
      operationId: get-encrypted-card-related-to-gateway-token
      parameters:
        - $ref: '#/components/parameters/ownerId'
        - $ref: '#/components/parameters/ownerType'
        - $ref: '#/components/parameters/gatewayTokenId'
      responses:
        '200':
          description: Successful retrieval of encrypted card data
          content:
            application/json:
              schema:
                type: object
                properties:
                  encryptedPrimaryAccountNumber:
                    $ref: '#/components/schemas/encryptedPrimaryAccountNumber'
                  expiryMonth:
                    $ref: '#/components/schemas/expiryMonth'
                  expiryYear:
                    $ref: '#/components/schemas/expiryYear'
                  encryptedHolderName:
                    $ref: '#/components/schemas/encryptedHolderName'
                  fundingSource:
                    $ref: '#/components/schemas/fundingSource'
                additionalProperties: false
              examples:
                Get Gateway Token Encrypted Card Data Response:
                  value:
                    encryptedPrimaryAccountNumber: QWxhZGRpbjpvcGVuIHNlc2FtZQ==
                    expiryMonth: '12'
                    expiryYear: '2025'
                    encryptedHolderName: Sm9obiBEb2U=
                    fundingSource: Credit
        '400':
          description: Bad request due to invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorised access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity due to semantic errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /token-vault/{ownerType}/{ownerId}/vaults/gateway-tokens/{gatewayTokenId}/card-verification-code:
    put:
      summary: Store card verification code for card
      description: >-
        Request to store the card verification code (CVC) for a card associated
        with a gateway token.
      operationId: store-security-code
      parameters:
        - $ref: '#/components/parameters/ownerId'
        - $ref: '#/components/parameters/ownerType'
        - $ref: '#/components/parameters/gatewayTokenId'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - cardVerificationCode
              type: object
              properties:
                cardVerificationCode:
                  $ref: '#/components/schemas/cardVerificationCode'
              additionalProperties: false
      responses:
        '200':
          description: Successful storage of the card verification code
        '400':
          description: Bad request due to invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorised access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity due to semantic errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    ownerId:
      name: ownerId
      in: path
      description: >-
        The unique identifier of the entity that owns the token (e.g., Referrer,
        Merchant Group, Merchant or Site).
      required: true
      example: MERCHANT-GROUP-1
      style: simple
      schema:
        maxLength: 20
        minLength: 0
        type: string
    ownerType:
      name: ownerType
      in: path
      description: >-
        The type of entity that owns the token (e.g., Referrer, MerchantGroup,
        Merchant or Site).
      required: true
      example: MerchantGroup
      style: simple
      schema:
        enum:
          - Referrer
          - MerchantGroup
          - Merchant
          - Site
        type: string
    schemeTokenId:
      name: schemeTokenId
      in: path
      description: >-
        The unique scheme token ID generated by PXP. It is used as a reference
        to extract the schemeTokenNumber.
      required: true
      style: simple
      schema:
        type: string
    gatewayTokenId:
      name: gatewayTokenId
      in: path
      description: >-
        The gateway token ID represents a securely stored token that corresponds
        to a previously saved payment card.
      required: true
      style: simple
      schema:
        type: string
        format: uuid
  schemas:
    ErrorResponse:
      type: object
      properties:
        correlationId:
          $ref: '#/components/schemas/correlationId'
        details:
          $ref: '#/components/schemas/details'
        errorCode:
          $ref: '#/components/schemas/errorCode'
        errorReason:
          $ref: '#/components/schemas/errorReason'
    cardVerificationCode:
      description: >-
        The Card Verification Code (CVC) associated with the payment card, a
        security feature for transactions where the card is not physically
        present. The security code is typically a 3 or 4 digit number found on
        the card, used to verify that the cardholder is in possession of the
        card during non-face-to-face transactions.
      type: string
      example: '123'
      nullable: true
      minLength: 3
      maxLength: 4
    encryptedHolderName:
      description: The encrypted name of the cardholder.
      type: string
      example: Sm9obiBEb2U=
      format: byte
    encryptedPrimaryAccountNumber:
      description: The encrypted primary account number (PAN) of the card.
      type: string
      format: byte
      example: QWxhZGRpbjpvcGVuIHNlc2FtZQ==
    expiryMonth:
      description: The expiry month of the card.
      type: string
      example: '03'
      minLength: 1
      maxLength: 2
    expiryYear:
      description: The expiry year of the card.
      type: string
      example: '2027'
      minLength: 4
      maxLength: 4
    fundingSource:
      description: The funding source type.
      type: string
      nullable: true
      example: Credit
    gatewayTokenId:
      description: >-
        The gateway token ID represents a securely stored token that corresponds
        to a previously saved payment card. This token is generated and
        maintained by PXP to facilitate recurring transactions or transactions
        using stored card details, ensuring enhanced security and convenience.
        When a transaction is performed with a saved card, this token Id should
        be provided instead of the full card details. This approach enhances
        security by reducing the exposure of sensitive card information and
        simplifies the transaction process for returning customers.
      type: string
      example: 7f46c09d-d1d1-4f94-9a88-6e8ac32e6341
      format: uuid
    holderName:
      description: >-
        The full name of the individual who owns the payment card. This name is
        printed on the physical card and is used for verifying the cardholder's
        identity during transactions. The cardholder name is a vital component
        for transaction processing, especially in cases of card-not-present
        transactions like online purchases. It should be treated with
        confidentiality to safeguard the cardholder's privacy and prevent
        potential misuse.
      type: string
      example: Mr John Doe
    maskedPrimaryAccountNumber:
      description: The masked primary account number (PAN) of the card.
      type: string
      example: 123456******7890
    primaryAccountNumber:
      description: >-
        The unique number assigned to a payment card, such as a credit or debit
        card. This number typically contains 16 digits, structured in a specific
        format to indicate the card network, issuing bank, and account number.
      type: string
      example: '4111111111111111111'
    schemeTokenCryptogram:
      description: >-
        A unique cryptogram generated during the tokenisation process, used to
        enhance the security of transaction processing. This cryptogram acts as
        a secure and unique identifier, akin to the TAVV, ensuring that each
        transaction is authenticated and verified without directly using
        sensitive card details. It plays a crucial role in the secure electronic
        payment ecosystem, especially in tokenised transactions, by providing an
        additional layer of security and authentication.
      type: string
      example: E1F53135E559C253
      nullable: true
    Pxp.Unity.Api.Gateway.Transactions.Contracts.TokenVault.Requests.AddCardVerificationCodeRequestBody:
      required:
        - cardVerificationCode
      type: object
      properties:
        cardVerificationCode:
          $ref: '#/components/schemas/cardVerificationCode'
      additionalProperties: false
    Pxp.Unity.Api.Gateway.Transactions.Contracts.TokenVault.Requests.CreateGatewayTokenRequest:
      required:
        - primaryAccountNumber
        - expiryMonth
        - expiryYear
        - holderName
      type: object
      properties:
        primaryAccountNumber:
          $ref: '#/components/schemas/primaryAccountNumber'
        expiryMonth:
          $ref: '#/components/schemas/expiryMonth'
        expiryYear:
          $ref: '#/components/schemas/expiryYear'
        cardVerificationCode:
          $ref: '#/components/schemas/cardVerificationCode'
        holderName:
          $ref: '#/components/schemas/holderName'
      additionalProperties: false
    Pxp.Unity.Api.Gateway.Transactions.Contracts.TokenVault.Requests.CreateSchemeTokenRequest:
      required:
        - primaryAccountNumber
        - expiryMonth
        - expiryYear
        - holderName
      type: object
      properties:
        primaryAccountNumber:
          $ref: '#/components/schemas/primaryAccountNumber'
        expiryMonth:
          $ref: '#/components/schemas/expiryMonth'
        expiryYear:
          $ref: '#/components/schemas/expiryYear'
        cardVerificationCode:
          $ref: '#/components/schemas/cardVerificationCode'
        holderName:
          $ref: '#/components/schemas/holderName'
      additionalProperties: false
    Pxp.Unity.Api.Gateway.Transactions.Contracts.TokenVault.Responses.CryptogramResponse:
      type: object
      properties:
        schemeTokenCryptogram:
          $ref: '#/components/schemas/schemeTokenCryptogram'
        schemeTokenNumber:
          description: >-
            The scheme token number represents a scheme token issued by Visa or
            Mastercard, used for subsequent transaction processing. This token
            enhances security and facilitates recurring transactions, providing
            a secure and efficient alternative to sharing sensitive card
            details.
          type: string
          example: '4837261112345678'
        cryptogramType:
          description: The type of cryptogram (e.g., 3DSecure).
          type: string
          example: 3DSecure
          nullable: true
        clientPaymentDataId:
          description: The client payment data identifier associated with the cryptogram.
          type: string
          nullable: true
          example: abc123
      additionalProperties: false
    Pxp.Unity.Api.Gateway.Transactions.Contracts.TokenVault.Responses.GatewayTokenResponse:
      type: object
      properties:
        gatewayTokenId:
          $ref: '#/components/schemas/gatewayTokenId'
        maskedPrimaryAccountNumber:
          $ref: '#/components/schemas/maskedPrimaryAccountNumber'
        fundingSource:
          $ref: '#/components/schemas/fundingSource'
      additionalProperties: false
    Pxp.Unity.Api.Gateway.Transactions.Contracts.TokenVault.Responses.GetGatewayTokenCardDataResponse:
      type: object
      properties:
        maskedPrimaryAccountNumber:
          $ref: '#/components/schemas/maskedPrimaryAccountNumber'
        expiryMonth:
          $ref: '#/components/schemas/expiryMonth'
        expiryYear:
          $ref: '#/components/schemas/expiryYear'
        holderName:
          $ref: '#/components/schemas/holderName'
        fundingSource:
          $ref: '#/components/schemas/fundingSource'
      additionalProperties: false
    Pxp.Unity.Api.Gateway.Transactions.Contracts.TokenVault.Responses.GetGatewayTokenEncryptedCardDataResponse:
      type: object
      properties:
        encryptedPrimaryAccountNumber:
          $ref: '#/components/schemas/encryptedPrimaryAccountNumber'
        expiryMonth:
          $ref: '#/components/schemas/expiryMonth'
        expiryYear:
          $ref: '#/components/schemas/expiryYear'
        encryptedHolderName:
          $ref: '#/components/schemas/encryptedHolderName'
        fundingSource:
          $ref: '#/components/schemas/fundingSource'
      additionalProperties: false
    Pxp.Unity.Api.Gateway.Transactions.Contracts.TokenVault.Responses.SchemeTokenResponse:
      type: object
      properties:
        schemeTokenId:
          description: >-
            The unique scheme token ID generated by PXP. It is used as a
            reference to extract the schemeTokenNumber.
          type: string
          format: uuid
        fundingSource:
          $ref: '#/components/schemas/fundingSource'
      additionalProperties: false
    Pxp.Unity.Api.Gateway.Transactions.Contracts.TokenVault.Responses.GetSchemeTokenResponse:
      type: object
      properties:
        schemeTokenId:
          type: string
          format: uuid
          description: >-
            The unique scheme token ID generated by PXP. It is used as a
            reference to extract the `schemeTokenNumber`.
        schemeTokenProvider:
          type: string
          description: The name of the scheme token provider.
        schemeTokenProcurementState:
          type: string
          description: The procurement state of the scheme token.
        externalschemeTokenId:
          type: string
          nullable: true
          description: >-
            A unique identifier token provided by the external payment scheme.
            This token allows merchants to process payments through different
            payment service providers (PSPs) or transaction service providers
            (TSPs). The token facilitates interoperability between different
            PSPs, enabling merchants to seamlessly integrate with and use
            various payment processing services.
        status:
          type: string
          nullable: true
          description: The status of the scheme token.
        paymentAccountReference:
          type: string
          nullable: true
          description: The payment account reference associated with the scheme token.
        schemeTokenNumber:
          type: string
          nullable: true
          description: >-
            The scheme token number represents a scheme token issued by Visa or
            Mastercard, used for subsequent transaction processing. This token
            enhances security and facilitates recurring transactions, providing
            a secure and efficient alternative to sharing sensitive card
            details.
        expiryMonth:
          $ref: '#/components/schemas/expiryMonth'
        expiryYear:
          $ref: '#/components/schemas/expiryYear'
    correlationId:
      type: string
      description: >-
        A unique identifier generated by PXP, serving as a critical tool for
        tracing and diagnosing transaction errors. This Id allows for the
        precise location of transactional issues, facilitating swift
        investigation and resolution by correlating specific transaction
        attempts or processes with error logs. Essential for support and
        operational teams, the correlationId enhances PXP's ability to maintain
        high-quality service and transaction reliability.
      example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
    details:
      type: array
      items: {}
      description: Additional details about the error.
    errorCode:
      type: string
      description: The error code returned for the operation.
      example: INVALID_REQUEST
    errorReason:
      type: string
      description: The error reason returned for the operation.
      example: The request parameters are invalid.
