Fiserv Refunds API

openapi: 3.2.0
info:
  title: Fiserv CommerceHub Refunds 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: Refunds
  description: Process refunds against previously captured transactions.
paths:
  /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'
components:
  parameters:
    Authorization:
      name: Authorization
      in: header
      required: true
      schema:
        type: string
      description: HMAC authorization token for request authentication.
    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.
    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.
    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.
    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.
    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.
    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.
    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'
    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'
  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