openapi: 3.1.0
info:
  title: Fiserv CommerceHub 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
externalDocs:
  description: CommerceHub API Documentation
  url: https://developer.fiserv.com/product/CommerceHub/docs/?path=docs/Resources/API-Documents/Use-Our-APIs.md
servers:
  - url: https://connect-cert.fiservapis.com/ch
    description: Certification Environment
  - url: https://connect.fiservapis.com/ch
    description: Production Environment
tags:
  - name: 3-D Secure
    description: >-
      Manage 3-D Secure authentication flows for cardholder verification.
  - name: Cancels
    description: >-
      Cancel or void previously authorized transactions.
  - name: Captures
    description: >-
      Capture previously authorized transactions for settlement.
  - name: Charges
    description: >-
      Process payment charges including authorizations, sales, and
      pre-authorizations.
  - name: Refunds
    description: >-
      Process refunds against previously captured transactions.
  - name: Tokens
    description: >-
      Create, manage, and use payment tokens for secure storage of
      payment credentials.
  - name: Verifications
    description: >-
      Verify payment cards or tokens before processing a transaction.
security:
  - apiKeyAuth: []
    hmacAuth: []
paths:
  /payments/v1/charges:
    post:
      operationId: createCharge
      summary: Fiserv Process a payment charge
      description: >-
        Submits a charge request to process a payment transaction. Supports
        authorization-only, sale (authorization and capture), and
        pre-authorization transaction types. The request can include payment
        source details such as card data, tokens, or encrypted payment data.
      tags:
        - Charges
      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/ChargeRequest'
      responses:
        '200':
          description: Charge processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /payments/v1/charges/{transactionId}/capture:
    post:
      operationId: captureCharge
      summary: Fiserv Capture an authorized payment
      description: >-
        Captures a previously authorized transaction for settlement. The
        capture amount can be equal to or less than the original
        authorization amount.
      tags:
        - Captures
      parameters:
        - $ref: '#/components/parameters/ContentType'
        - $ref: '#/components/parameters/ClientRequestId'
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/Timestamp'
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/TransactionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CaptureRequest'
      responses:
        '200':
          description: Capture processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaptureResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Transaction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /payments/v1/charges/{transactionId}/cancel:
    post:
      operationId: cancelCharge
      summary: Fiserv Cancel or void a transaction
      description: >-
        Cancels or voids a previously authorized transaction. If the
        transaction has not yet been captured, it will be voided. If it
        has been captured but not yet settled, a reversal will be attempted.
      tags:
        - Cancels
      parameters:
        - $ref: '#/components/parameters/ContentType'
        - $ref: '#/components/parameters/ClientRequestId'
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/Timestamp'
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/TransactionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelRequest'
      responses:
        '200':
          description: Cancel processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Transaction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /payments/v1/charges/{transactionId}/refund:
    post:
      operationId: refundCharge
      summary: Fiserv Refund a captured transaction
      description: >-
        Processes a refund against a previously captured and settled
        transaction. Supports full and partial refunds. The refund amount
        must not exceed the original captured amount minus any previous
        refunds.
      tags:
        - Refunds
      parameters:
        - $ref: '#/components/parameters/ContentType'
        - $ref: '#/components/parameters/ClientRequestId'
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/Timestamp'
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/TransactionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundRequest'
      responses:
        '200':
          description: Refund processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Transaction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /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'
  /payments-vas/v1/accounts/verification:
    post:
      operationId: verifyAccount
      summary: Fiserv Verify a payment account
      description: >-
        Verifies a payment card or token to confirm it is valid before
        processing a transaction. This can include address verification
        (AVS) and card security code (CVV) validation.
      tags:
        - Verifications
      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/VerificationRequest'
      responses:
        '200':
          description: Verification completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /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:
        - 3-D 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:
  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.
  parameters:
    ContentType:
      name: Content-Type
      in: header
      required: true
      schema:
        type: string
        default: application/json
      description: >-
        The media type of the request body.
    ClientRequestId:
      name: Client-Request-Id
      in: header
      required: true
      schema:
        type: string
      description: >-
        A unique identifier for the request, used for idempotency and
        troubleshooting.
    ApiKey:
      name: Api-Key
      in: header
      required: true
      schema:
        type: string
      description: >-
        The API key assigned to the merchant.
    Timestamp:
      name: Timestamp
      in: header
      required: true
      schema:
        type: integer
        format: int64
      description: >-
        Epoch timestamp in milliseconds of the request.
    Authorization:
      name: Authorization
      in: header
      required: true
      schema:
        type: string
      description: >-
        HMAC authorization token for request authentication.
    TransactionId:
      name: transactionId
      in: path
      required: true
      schema:
        type: string
      description: >-
        The unique identifier of the original transaction.
  schemas:
    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.
    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).
    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.
    TransactionDetails:
      type: object
      description: >-
        Additional details about the transaction.
      properties:
        captureFlag:
          type: boolean
          description: >-
            When true, the transaction is captured immediately (sale).
            When false, the transaction is authorized only.
        merchantOrderId:
          type: string
          description: >-
            The merchant-assigned order identifier.
        merchantTransactionId:
          type: string
          description: >-
            The merchant-assigned transaction identifier.
    ChargeRequest:
      type: object
      description: >-
        Request body for creating a charge transaction.
      required:
        - amount
        - source
      properties:
        amount:
          $ref: '#/components/schemas/Amount'
        source:
          $ref: '#/components/schemas/PaymentSource'
        transactionDetails:
          $ref: '#/components/schemas/TransactionDetails'
    ChargeResponse:
      type: object
      description: >-
        Response body for a charge transaction.
      properties:
        gatewayResponse:
          $ref: '#/components/schemas/GatewayResponse'
        source:
          $ref: '#/components/schemas/PaymentSource'
        transactionProcessingDetails:
          $ref: '#/components/schemas/TransactionProcessingDetails'
        paymentReceipt:
          $ref: '#/components/schemas/PaymentReceipt'
    CaptureRequest:
      type: object
      description: >-
        Request body for capturing an authorized transaction.
      properties:
        amount:
          $ref: '#/components/schemas/Amount'
        transactionDetails:
          $ref: '#/components/schemas/TransactionDetails'
    CaptureResponse:
      type: object
      description: >-
        Response body for a capture transaction.
      properties:
        gatewayResponse:
          $ref: '#/components/schemas/GatewayResponse'
        transactionProcessingDetails:
          $ref: '#/components/schemas/TransactionProcessingDetails'
    CancelRequest:
      type: object
      description: >-
        Request body for cancelling or voiding a transaction.
      properties:
        amount:
          $ref: '#/components/schemas/Amount'
        transactionDetails:
          $ref: '#/components/schemas/TransactionDetails'
    CancelResponse:
      type: object
      description: >-
        Response body for a cancel transaction.
      properties:
        gatewayResponse:
          $ref: '#/components/schemas/GatewayResponse'
        transactionProcessingDetails:
          $ref: '#/components/schemas/TransactionProcessingDetails'
    RefundRequest:
      type: object
      description: >-
        Request body for refunding a captured transaction.
      properties:
        amount:
          $ref: '#/components/schemas/Amount'
        transactionDetails:
          $ref: '#/components/schemas/TransactionDetails'
    RefundResponse:
      type: object
      description: >-
        Response body for a refund transaction.
      properties:
        gatewayResponse:
          $ref: '#/components/schemas/GatewayResponse'
        transactionProcessingDetails:
          $ref: '#/components/schemas/TransactionProcessingDetails'
    TokenRequest:
      type: object
      description: >-
        Request body for creating a payment token.
      required:
        - source
      properties:
        source:
          $ref: '#/components/schemas/PaymentSource'
    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.
    VerificationRequest:
      type: object
      description: >-
        Request body for verifying a payment account.
      required:
        - source
      properties:
        source:
          $ref: '#/components/schemas/PaymentSource'
    VerificationResponse:
      type: object
      description: >-
        Response body for account verification.
      properties:
        gatewayResponse:
          $ref: '#/components/schemas/GatewayResponse'
        verificationStatus:
          type: string
          description: >-
            The outcome of the verification check.
    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'
    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.
    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.
    PaymentReceipt:
      type: object
      description: >-
        Payment receipt details including processor response.
      properties:
        approvedAmount:
          $ref: '#/components/schemas/Amount'
        processorResponseDetails:
          type: object
          description: >-
            Response details from the payment processor.
          properties:
            approvalStatus:
              type: string
              enum:
                - APPROVED
                - DECLINED
                - PROCESSING_FAILED
              description: >-
                The approval status from the processor.
            approvalCode:
              type: string
              description: >-
                The approval code from the issuer.
            responseCode:
              type: string
              description: >-
                The processor response code.
            responseMessage:
              type: string
              description: >-
                The processor response message.
    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.