openapi: 3.2.0
info:
  title: Fiserv CommerceHub 3-D Secure API
  description: The Fiserv CommerceHub API provides a unified RESTful interface for processing payments, managing tokens, verifying payment sources, and handling 3-D Secure authentication. CommerceHub enables merchants to accept payments through multiple channels including online, mobile, and in-app, with support for charges, pre-authorizations, captures, refunds, cancellations, and tokenization of payment credentials.
  version: 1.0.0
  contact:
    name: Fiserv Developer Support
    url: https://developer.fiserv.com/support
  termsOfService: https://www.fiserv.com/en/legal.html
servers:
- url: https://connect-cert.fiservapis.com/ch
  description: Certification Environment
- url: https://connect.fiservapis.com/ch
  description: Production Environment
security:
- apiKeyAuth: []
  hmacAuth: []
tags:
- name: 3D Secure
  description: Manage 3-D Secure authentication flows for cardholder verification.
paths:
  /payments-vas/v1/3ds/authentication:
    post:
      operationId: authenticate3DS
      summary: Fiserv Initiate 3-D Secure authentication
      description: Initiates a 3-D Secure authentication flow for cardholder verification. This step is used to authenticate the cardholder before processing a payment, enabling Strong Customer Authentication (SCA) compliance and potential liability shift.
      tags:
      - 3D Secure
      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/ThreeDSAuthenticationRequest'
      responses:
        '200':
          description: 3-D Secure authentication initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreeDSAuthenticationResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    ClientRequestId:
      name: Client-Request-Id
      in: header
      required: true
      schema:
        type: string
      description: A unique identifier for the request, used for idempotency and troubleshooting.
    Timestamp:
      name: Timestamp
      in: header
      required: true
      schema:
        type: integer
        format: int64
      description: Epoch timestamp in milliseconds of the request.
    ApiKey:
      name: Api-Key
      in: header
      required: true
      schema:
        type: string
      description: The API key assigned to the merchant.
    ContentType:
      name: Content-Type
      in: header
      required: true
      schema:
        type: string
        default: application/json
      description: The media type of the request body.
    Authorization:
      name: Authorization
      in: header
      required: true
      schema:
        type: string
      description: HMAC authorization token for request authentication.
  schemas:
    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).
    ThreeDSAuthenticationResponse:
      type: object
      description: Response body for 3-D Secure authentication.
      properties:
        gatewayResponse:
          $ref: '#/components/schemas/GatewayResponse'
        authenticationStatus:
          type: string
          description: The status of the 3-D Secure authentication.
        authenticationValue:
          type: string
          description: The authentication value (CAVV/AAV) from the issuer.
    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.
    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'
    Amount:
      type: object
      description: Represents a monetary amount with currency.
      properties:
        total:
          type: number
          format: double
          description: The total transaction amount.
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          description: The ISO 4217 three-letter currency code.
    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.
    ThreeDSAuthenticationRequest:
      type: object
      description: Request body for initiating 3-D Secure authentication.
      required:
      - source
      properties:
        source:
          $ref: '#/components/schemas/PaymentSource'
        amount:
          $ref: '#/components/schemas/Amount'
    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'
    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.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Api-Key
      description: API key provided by Fiserv for authenticating requests.
    hmacAuth:
      type: apiKey
      in: header
      name: Authorization
      description: HMAC signature generated using the API secret, request timestamp, and request payload for message integrity verification.
externalDocs:
  description: CommerceHub API Documentation
  url: https://developer.fiserv.com/product/CommerceHub/docs/?path=docs/Resources/API-Documents/Use-Our-APIs.md