openapi: 3.1.0
info:
  title: Fiserv BankingHub 3-D Secure Tokens API
  description: The Fiserv BankingHub API provides RESTful access to core banking operations including account management, transactions, transfers, payments, and party (customer) management. BankingHub enables financial institutions and fintech partners to integrate account opening, fund transfers, payment processing, and customer data management into their applications.
  version: 1.0.0
  contact:
    name: Fiserv Developer Support
    url: https://developer.fiserv.com/product/BankingHub
  termsOfService: https://www.fiserv.com/en/legal.html
servers:
- url: https://cert.api.fiservapps.com
  description: Certification Environment
- url: https://prod.api.fiservapps.com
  description: Production Environment
security:
- bearerAuth: []
tags:
- name: Tokens
  description: Create, manage, and use payment tokens for secure storage of payment credentials.
paths:
  /payments-vas/v1/tokens:
    post:
      operationId: createToken
      summary: Fiserv Create a payment token
      description: Tokenizes a payment source such as a card number, creating a secure token that can be used in subsequent transactions. This eliminates the need to store sensitive payment data and reduces PCI compliance scope.
      tags:
      - Tokens
      parameters:
      - $ref: '#/components/parameters/ContentType'
      - $ref: '#/components/parameters/ClientRequestId'
      - $ref: '#/components/parameters/ApiKey'
      - $ref: '#/components/parameters/Timestamp'
      - $ref: '#/components/parameters/Authorization'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: Token created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    PaymentSource:
      type: object
      description: The payment source for the transaction, such as a card or token.
      properties:
        sourceType:
          type: string
          enum:
          - PaymentCard
          - PaymentToken
          - PaymentSession
          - GooglePay
          - ApplePay
          description: The type of payment source being used.
        card:
          $ref: '#/components/schemas/Card'
        token:
          $ref: '#/components/schemas/Token'
    Card:
      type: object
      description: Payment card details.
      properties:
        cardData:
          type: string
          description: The card number (PAN) or encrypted card data.
        expirationMonth:
          type: string
          pattern: ^\d{2}$
          description: Card expiration month in MM format.
        expirationYear:
          type: string
          pattern: ^\d{4}$
          description: Card expiration year in YYYY format.
        securityCode:
          type: string
          description: The card verification value (CVV/CVC).
    TokenResponse:
      type: object
      description: Response body for token creation.
      properties:
        gatewayResponse:
          $ref: '#/components/schemas/GatewayResponse'
        source:
          $ref: '#/components/schemas/PaymentSource'
        paymentTokens:
          type: array
          items:
            $ref: '#/components/schemas/Token'
          description: The generated payment tokens.
    TokenRequest:
      type: object
      description: Request body for creating a payment token.
      required:
      - source
      properties:
        source:
          $ref: '#/components/schemas/PaymentSource'
    GatewayResponse:
      type: object
      description: The gateway processing response details.
      properties:
        transactionType:
          type: string
          description: The type of transaction that was processed.
        transactionState:
          type: string
          enum:
          - AUTHORIZED
          - CAPTURED
          - DECLINED
          - VOIDED
          - REFUNDED
          description: The current state of the transaction.
        transactionProcessingDetails:
          $ref: '#/components/schemas/TransactionProcessingDetails'
    Token:
      type: object
      description: Payment token details.
      properties:
        tokenData:
          type: string
          description: The token value representing the stored payment credential.
        tokenSource:
          type: string
          description: The source or provider of the token.
        expirationMonth:
          type: string
          pattern: ^\d{2}$
          description: Token expiration month in MM format.
        expirationYear:
          type: string
          pattern: ^\d{4}$
          description: Token expiration year in YYYY format.
    ErrorResponse:
      type: object
      description: Error response returned when a request fails.
      properties:
        error:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                description: The error type classification.
              code:
                type: string
                description: The error code.
              message:
                type: string
                description: A human-readable error message.
              field:
                type: string
                description: The field that caused the error, if applicable.
    TransactionProcessingDetails:
      type: object
      description: Transaction processing identifiers and details.
      properties:
        transactionId:
          type: string
          description: The gateway-assigned transaction identifier.
        orderId:
          type: string
          description: The order identifier associated with the transaction.
        transactionTimestamp:
          type: string
          format: date-time
          description: The timestamp when the transaction was processed.
        apiTraceId:
          type: string
          description: A unique trace identifier for the API request.
  parameters:
    ApiKey:
      name: Api-Key
      in: header
      required: true
      schema:
        type: string
      description: The API key assigned to the merchant.
    Authorization:
      name: Authorization
      in: header
      required: true
      schema:
        type: string
      description: HMAC authorization token for request authentication.
    Timestamp:
      name: Timestamp
      in: header
      required: true
      schema:
        type: integer
        format: int64
      description: Epoch timestamp in milliseconds of the request.
    ClientRequestId:
      name: Client-Request-Id
      in: header
      required: true
      schema:
        type: string
      description: A unique identifier for the request, used for idempotency and troubleshooting.
    ContentType:
      name: Content-Type
      in: header
      required: true
      schema:
        type: string
        default: application/json
      description: The media type of the request body.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 Bearer token for API authentication.
externalDocs:
  description: BankingHub API Documentation
  url: https://developer.fiserv.com/product/BankingHub/docs/?path=docs/get-started.md