---
title: "Initiates a dispute for a specific transaction by forwarding transaction details to PayTic. This endpoint is called from the Thredd Portal when a user selects \"Initiate Dispute Flow\" for a transaction."
method: POST
path: "/api/v1/disputes/transactions/{transactionId}/initiate"
tags: ["Disputes"]
---

# Initiates a dispute for a specific transaction by forwarding transaction details to PayTic. This endpoint is called from the Thredd Portal when a user selects "Initiate Dispute Flow" for a transaction.

`POST /api/v1/disputes/transactions/{transactionId}/initiate`

## Request

- Base URL: `https://cardsapi-uat-pub.globalprocessing.net`
- URL: `https://cardsapi-uat-pub.globalprocessing.net/api/v1/disputes/transactions/{transactionId}/initiate`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://uatists.globalprocessing.net/connect/token` scopes: `readWrite`

Authentication requirements:
- User must have either ChargebackManager OR ChargebackClaims policy (at least one required)
- Valid PMID claim must be present in the authentication token

Process flow:
1. Validates transaction ID and user authorization
2. Retrieves comprehensive transaction details from database
3. Forwards transaction data to PayTic dispute management system
4. Returns success/failure response to Thredd Portal

## Path parameters

- `transactionId` string, required

## Request body

- InitiateDisputeRequest: Request model for initiating a dispute from the Thredd Portal. Used when a user selects "Initiate Dispute Flow" for a transaction.
  - `publicToken` string, required: Public token of the card associated with the disputed transaction. This field is required for PayTic to identify the cardholder.
  - `disputeReason` string, nullable: Optional reason for initiating the dispute. Provides context for the dispute initiation.
  - `notes` string, nullable: Optional additional notes or comments about the dispute. Can be used to provide extra context for the dispute team.
  - `transactionId` string, nullable: The transaction identifier (populated from route parameter, not request body). Internal use only - set by the controller.

## Response `200`

Success

- InitiateDisputeResponse: Response model for dispute initiation operations. Returned when a dispute is successfully initiated or when an error occurs.
  - `success` boolean: Indicates whether the dispute was successfully initiated with PayTic.
  - `message` string, nullable: A message describing the result of the operation.
  - `transactionId` string, nullable: The transaction identifier that was submitted for dispute.
  - `processedAt` string, date-time: The timestamp when the dispute initiation was processed.
  - `disputeReferenceId` string, nullable: Optional dispute reference ID returned by PayTic. Used to track the dispute in PayTic's system.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `500`: Server Error
- `502`: Server Error

## Changes

- **2026-11-03** `a5b5e4fdcf41`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/thredd/apis/core-cards/changes/api/v1/disputes/transactions/:transactionId/initiate/post.md)

---

[API](https://skmtc.dev/thredd/apis/core-cards.md) - [All operations](https://skmtc.dev/thredd/apis/core-cards/llms.txt) - [OpenAPI document](https://skmtc.dev/thredd/apis/core-cards/revisions/a5b5e4fdcf41?raw)