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.
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.