> ## Documentation Index > Fetch the complete documentation index at: https://docs.rinne.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Get a single dispute by ID > Requires the dispute.view permission. Returns a single dispute by its ID, including its timeline of events. ## OpenAPI ````yaml /api-spec.yaml get /v1/disputes/{id} openapi: 3.1.0 info: title: Rinne API version: 1.0.0 description: > **Rinne API** is a robust payment platform that offers integration with multiple payment providers. ## Authentication The API uses API Key authentication via the `x-api-key` header. Each company has a unique key to access resources. ## Response Format All responses follow a consistent format: - **Success**: Returns the requested data directly - **Error**: Returns an `error` object with detailed information ## Pagination Endpoints that return lists support pagination through parameters: - `page`: Page number (default: 1) - `limit`: Items per page (default: 20, maximum: 100) ## Supported Providers The API supports multiple payment providers: - **Rinne**: Internal provider - **Celcoin**: PIX integration and other financial services ## Raw Card Data (PCI Endpoints) Card credential fields (`card_data.number`, `card_data.cvv`, `card_data.network_token`, `card_data.cryptogram`, and the 3DS `card.number`) must always be sent encrypted — values start with the `ev:` prefix. Plaintext values are rejected with `400 VALIDATION_ERROR` on every host. There are two ways to send encrypted values: - **rinne-js**: card forms and wallet buttons (Apple Pay / Google Pay) encrypt credentials client-side before they leave the browser. - **PCI API host**: server-to-server integrations that handle raw card data must call `https://pci.api.rinne.com.br/core` (sandbox: `https://pci.api-sandbox.rinne.com.br/core`) instead of the regular host. This endpoint encrypts `number` and `cvv` in transit before the request reaches the API; all other fields pass through unchanged. The PCI host serves only transaction creation and 3DS session creation (both the self and merchant variants); use the regular host for everything else. contact: name: Rinne API Support email: suporte@rinne.com.br servers: - url: https://api-sandbox.rinne.com.br/core description: Sandbox - url: https://api.rinne.com.br/core description: Production security: [] tags: - name: System description: System and API health endpoints - name: Tap-on-Phone description: Access-token minting for the Tap-on-Phone SDK (called from your backend) - name: Authentication description: User authentication and authorization endpoints - name: Management description: >- Merchant management endpoints - create, list, get specific, overview, update - name: Transactions description: Transaction operations for merchants - create, list, overview, refunds - name: Affiliations description: Affiliation management for merchants - name: KYC description: KYC check history of your merchants - name: Banking description: Banking operations for merchants - balance, cashout, statements - name: Bank Accounts description: Bank account management for merchants - name: Pix Keys description: PIX key management for merchants - name: Company Transactions description: Direct transaction management and query endpoints for companies - name: Companies description: Company management - name: Company Affiliations description: Payment provider affiliation management - name: Company Banking description: Company banking endpoints (balance, etc.) - name: Company Pix description: Company PIX key management - name: Company Ledger description: Company ledger entry query endpoints - name: Company Disputes description: Company dispute query endpoints - name: Ledger description: Ledger entry query endpoints (company and merchants) - name: Disputes description: Dispute query endpoints for an organization's merchants - name: Cards description: Stored card management (self and merchant) - name: API Keys description: API key management - create, list, revoke (hashed, show-once) - name: Webhooks description: Endpoints for receiving webhooks from external providers - name: Pricing description: Fee and cost policy management for transaction pricing - name: Users description: User management endpoints - name: Roles description: Role management endpoints - name: Permissions description: Permission management endpoints paths: /v1/disputes/{id}: get: tags: - Company Disputes summary: Get a single dispute by ID description: | Requires the dispute.view permission. Returns a single dispute by its ID, including its timeline of events. parameters: - in: path name: id required: true schema: type: string description: The dispute ID example: 123e4567-e89b-12d3-a456-426614174000 responses: '200': description: Dispute details with timeline content: application/json: schema: $ref: '#/components/schemas/DisputeWithTimelineResponse' '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/AuthenticationErrorResponse' '403': description: Insufficient permissions to access this resource content: application/json: schema: $ref: '#/components/schemas/AuthorizationErrorResponse' '404': description: Dispute not found or does not belong to authenticated company content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorResponse' security: - ApiKeyAuth: [] components: schemas: DisputeWithTimelineResponse: allOf: - $ref: '#/components/schemas/DisputeResponse' - type: object description: Dispute with its timeline of events, oldest first required: - timeline properties: timeline: type: array description: Timeline of dispute events, oldest first items: $ref: '#/components/schemas/DisputeTimelineEntryResponse' AuthenticationErrorResponse: type: object properties: error: type: object properties: code: type: string example: AUTHENTICATION_ERROR message: type: string example: Authentication required to access this resource status: type: integer example: 401 details: type: object properties: reason: type: string example: Invalid API key path: type: string example: /companies/me timestamp: type: string format: date-time example: '2023-12-01T10:00:00.000Z' requestId: type: string example: req_123456789 AuthorizationErrorResponse: type: object properties: error: type: object properties: code: type: string example: AUTHORIZATION_ERROR message: type: string example: You need 'admin' permissions to access this resource status: type: integer example: 403 path: type: string example: /companies timestamp: type: string format: date-time example: '2023-12-01T10:00:00.000Z' requestId: type: string example: req_123456789 NotFoundErrorResponse: type: object properties: error: type: object properties: code: type: string example: RESOURCE_NOT_FOUND message: type: string example: Company with ID '123' not found status: type: integer example: 404 path: type: string example: /companies/me timestamp: type: string format: date-time example: '2023-12-01T10:00:00.000Z' requestId: type: string example: req_123456789 InternalServerErrorResponse: type: object properties: error: type: object properties: code: type: string example: INTERNAL_SERVER_ERROR message: type: string example: An unexpected error occurred status: type: integer example: 500 path: type: string example: /companies timestamp: type: string format: date-time example: '2023-12-01T10:00:00.000Z' requestId: type: string example: req_123456789 DisputeResponse: description: A provider-initiated challenge against a settled payment allOf: - $ref: '#/components/schemas/DisputeEntitySnapshot' - type: object required: - company_name - company_full_name DisputeTimelineEntryResponse: type: object description: One event in a dispute's history required: - id - type - created_at properties: id: type: string format: uuid description: Timeline entry ID example: 123e4567-e89b-12d3-a456-426614174010 type: type: string enum: - DISPUTE_RECEIVED - STATUS_CHANGED - FUNDS_HELD - FUNDS_RELEASED - FUNDS_RETURNED - PROVIDER_RESPONSE_SENT - INVESTIGATION_COMPLETED description: What happened example: DISPUTE_RECEIVED created_at: type: string format: date-time example: '2026-08-05T15:16:57.000Z' DisputeEntitySnapshot: type: object description: > Dispute object as sent in the `entity` snapshot of every `dispute.*` webhook. Same shape as `DisputeResponse`, except that `company_name` and `company_full_name` may be absent: they were added after the events existed, and a snapshot is taken when the event is written, so an event written before then and delivered later carries neither. required: - id - transaction_id - company_id - organization_id - provider - type - status - outcome - amount - provider_dispute_id - dispute_details - deadline_at - concluded_at - created_at - updated_at properties: id: type: string format: uuid description: Internal dispute ID example: 123e4567-e89b-12d3-a456-426614174000 transaction_id: type: string format: uuid description: ID of the disputed transaction example: 123e4567-e89b-12d3-a456-426614174001 company_id: type: string format: uuid description: Merchant the claim is filed against example: 123e4567-e89b-12d3-a456-426614174002 company_name: type: - string - 'null' description: Trading name of the merchant the claim is filed against example: Acme company_full_name: type: string description: Legal name of the merchant the claim is filed against example: Acme Payments LTDA organization_id: type: string format: uuid description: Organization the merchant belongs to example: 123e4567-e89b-12d3-a456-426614174003 provider: type: string enum: - CELCOIN - RINNE - CAPPTA description: Provider that processed the disputed transaction example: CELCOIN type: type: string enum: - PIX_INFRACTION - CHARGEBACK description: Rail the dispute arrived on example: PIX_INFRACTION status: type: string enum: - OPEN - UNDER_REVIEW - CLOSED description: > Ordered progression; a dispute only moves forward. CLOSED is terminal, so a finished dispute is exactly `status == CLOSED`. example: OPEN outcome: type: string nullable: true enum: - UPHELD - DISMISSED - WITHDRAWN description: > The verdict. Null until the dispute closes, and always set once it has. UPHELD means the claim succeeded and funds are returned; DISMISSED means it failed; WITHDRAWN means it ceased before a verdict, or the provider closed out a dismissed claim. A closed dispute's outcome may move between DISMISSED and WITHDRAWN without a further dispute.status-changed event; UPHELD never changes. example: null amount: type: integer description: > Amount at risk in cents. Derived from the disputed transaction when the dispute is created (an upper bound rather than an exact figure); once the provider reports the exact amount it set out to hold, that figure supersedes the derived one. example: 9500 provider_dispute_id: type: string description: The provider's own identifier for the dispute example: aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee dispute_details: type: string nullable: true description: > Free text describing the dispute, directly or indirectly, as supplied by the reporting side. The author is not recorded and may be the payer, a risk analyst or a system. example: the reporting institution describes an unauthorised transfer deadline_at: type: string format: date-time nullable: true description: Provider-stated response deadline. Null where the rail states none. example: null concluded_at: type: string format: date-time nullable: true description: When the dispute concluded. Set exactly when status becomes CLOSED. example: null created_at: type: string format: date-time example: '2026-08-05T15:16:57.000Z' updated_at: type: string format: date-time example: '2026-08-05T15:16:57.000Z' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: Company API key for authentication ````