Dispute Request

This page will guide you through the endpoints for managing Pix transaction dispute requests. A dispute is a formal process where the customer questions a Pix transaction, claiming it was performed fraudulently, due to operational error, or without their authorization. Through these endpoints, you can create, query, list, and cancel dispute requests.

Create dispute request

This endpoint is used to create a new dispute request for a Pix transaction.

Request

URL
cURL

POST https://apisandbox.delbank.com.br/baas/api/v1/pix/med/disputes

curl -X POST https://apisandbox.delbank.com.br/baas/api/v1/pix/med/disputes \
  -H "Content-Type: application/json" \
  -H "x-delbank-api-key: ••••••" \
  -H "x-delfinance-account-id: ••••••" \
  -d '{
    "endToEndId": "E12345678202412101234567890123456",
    "disputeType": "OPERATIONAL_FAILURE",
    "details": "´Exemplo de detalhes"
  }'

Example for SUSPECTED_FRAUD (with SituationType):

curl -X POST https://apisandbox.delbank.com.br/baas/api/v1/pix/med/disputes\
  -H "Content-Type: application/json" \
  -H "x-delbank-api-key: ••••••" \
  -H "x-delfinance-account-id: ••••••" \
  -d '{
    "endToEndId": "E12345678202412101234567890123456",
    "disputeType": "SUSPECTED_FRAUD",
    "details": "´Exemplo de detalhes",
    "SituationType": "COERCION"
  }'

Headers

Name	Description
Content-Type	Required. application/json
x-delbank-api-key	Required. API key for authentication
x-delfinance-account-id	Required. Account identifier

Body Parameters

Parameter	Type	Description
endToEndId	`string`	Required. End-to-end identifier of the Pix transaction
disputeType	`enum`	Required. Type of dispute. Values: `OPERATIONAL_FAILURE` - Operational failure, `SUSPECTED_FRAUD` - Suspected fraud
details	`string`	Required. Details about the dispute (maximum 2,000 characters)
situationType	`enum`	Optional. Required only when disputeType is `SUSPECTED_FRAUD`. Values: `SCAM`, `ACCOUNT_TAKEOVER`, `COERCION`, `FRAUDULENT_ACCESS`, `OTHER`

Important Rules:

When using disputeType: "OPERATIONAL_FAILURE", do NOT include the SituationType field
When using disputeType: "SUSPECTED_FRAUD", the SituationType field is required

Example for OPERATIONAL_FAILURE:

{
  "endToEndId": "E38224857202509241500KUP1D9H8QX1",
  "disputeType": "OPERATIONAL_FAILURE",
  "details": "Exemplo"
}

Example for SUSPECTED_FRAUD:

{
  "endToEndId": "E38224857202509241500KUP1D9H8QX1",
  "disputeType": "SUSPECTED_FRAUD",
  "details": "Exemplo",
  "SituationType": "COERCION"
}

Response

The status code 201 indicates successful dispute creation.

If the request is successful, the response will have the following fields in JSON format:

{
  "id": "J3OKE0EBX8GKKUZC",
  "customerRole": "CLAIMANT",
  "accountNumber": "10138",
  "endToEndId": "E38224857202509251518IQT5PJKA64D",
  "disputeType": "OPERATIONAL_FAILURE",
  "transactionAmount": 8.00,
  "counterpartyName": "JOTINHA AFONSO",
  "status": "PENDING",
  "details": "Exemplo",
  "infractionNotificationId": null,
  "refundRequestId": null,
  "refundedAmount": null,
  "createdAt": "2025-10-01T16:54:45.865201657",
  "updatedAt": "2025-10-01T16:54:45.86520653",
  "deadlineAt": "2025-10-08T16:54:45.865207206",
  "analyzedAt": null,
  "analyzedBy": null,
  "analysisNotes": null
}

Cancel dispute

This endpoint allows you to cancel an existing dispute.

Request

URL
cURL

PATCH https://apisandbox.delbank.com.br/baas/api/v1/pix/med/disputes/:disputeId/cancel

curl --request PATCH \
  --url 'https://apisandbox.delbank.com.br/baas/api/v1/pix/med/disputes/DSP123456789/cancel' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-delbank-api-key: YOUR_API_KEY' \
  --header 'x-delfinance-account-id: YOUR_ACCOUNT_ID' \
  --data '{
    "reason": "Customer withdrew the dispute"
  }'

Headers

Name	Description
Content-Type	Required. application/json
x-delbank-api-key	Required. API key for authentication
x-delfinance-account-id	Required. Account identifier

Path Parameters:

Name	Type	Description
disputeId	`string`	Required. Dispute identifier

Body

{
  "reason": "Customer withdrew the dispute"
}

Response

The status code 200 indicates successful cancellation.

If the request is successful, the response will have the following fields in JSON format:

{
  "id": "LUPRY7ZN08XF6673",
  "customerRole": "CLAIMANT",
  "accountNumber": "10138",
  "endToEndId": "E3822485720250929125712cQXATZ4n9",
  "disputeType": "SUSPECTED_FRAUD",
  "transactionAmount": 10.00,
  "counterpartyName": "TESTE PESSOAL",
  "status": "CANCELED",
  "details": "Detalhes da criação da contestação",
  "infractionNotificationId": null,
  "refundRequestId": null,
  "refundedAmount": null,
  "createdAt": "2025-10-01T13:02:23.996737",
  "updatedAt": "2025-10-02T17:30:05.117778758",
  "deadlineAt": "2025-10-08T13:02:23.996746",
  "analyzedAt": null,
  "analyzedBy": null,
  "analysisNotes": "CANCELED BY CUSTOMER. Customer withdrew the dispute"
}

Get specific dispute

Use this endpoint to get information about a specific dispute.

Request

URL
cURL

GET https://apisandbox.delbank.com.br/baas/api/v1/pix/med/disputes/:disputeId

curl --request GET \
  --url 'https://apisandbox.delbank.com.br/baas/api/v1/pix/med/disputes/DSP123456789' \
  --header 'accept: application/json' \
  --header 'x-delbank-api-key: YOUR_API_KEY' \
  --header 'x-delfinance-account-id: YOUR_ACCOUNT_ID'

Headers

Name	Description
x-delbank-api-key	Required. API key
x-delfinance-account-id	Required. The Delfinance bank account number.

Path Parameters:

Name	Type	Description
disputeId	`string`	Required. Dispute identifier

Response

The status code 200 indicates successful query.

If the query is successful, the response will have the following fields in JSON format:

{
  "id": "01JH8XQZQZQZQZQZQZQZQZQZQZ",
  "customerRole": "CLAIMANT",
  "accountNumber": "12345678901",
  "endToEndId": "E38224857202501011234567890123456",
  "disputeType": "OPERATIONAL_FAILURE",
  "transactionAmount": 150.75,
  "counterpartyName": "João Silva",
  "status": "PENDING",
  "details": "Transação não reconhecida pelo cliente",
  "infractionNotificationId": "INF123456789",
  "refundRequestId": "REF987654321",
  "refundedAmount": 0.00,
  "createdAt": "2025-01-01T10:30:00.000Z",
  "updatedAt": "2025-01-01T10:30:00.000Z",
  "deadlineAt": "2025-01-15T23:59:59.999Z",
  "analyzedAt": null,
  "analyzedBy": null,
  "analysisNotes": "Aguardando análise da equipe de compliance"
}

List disputes

This endpoint allows you to search all disputes with optional filters.

Request

URL
cURL

GET https://apisandbox.delbank.com.br/baas/api/v1/pix/med/disputes

curl --request GET \
  --url 'https://apisandbox.delbank.com.br/baas/api/v1/pix/med/disputes?page=1&size=50' \
  --header 'accept: application/json' \
  --header 'x-delbank-api-key: YOUR_API_KEY' \
  --header 'x-delfinance-account-id: YOUR_ACCOUNT_ID'

Headers

Name	Description
Content-Type	Required. application/json
x-delbank-api-key	Required. API key for authentication
x-delfinance-account-id	Required. Account identifier

Query Parameters:

Name	Type	Description
page	`number`	Page number (default: 1)
size	`number`	Page size (default: 50)
disputeType	`enum`	Required. Dispute type. Values: `OPERATIONAL_FAILURE` - Operational failure, `SUSPECTED_FRAUD` - Suspected fraud
status	`enum`	Dispute status to filter. Values: `PENDING`, `CANCELED`, `AWAITING_EVIDENCE`, `ACCEPTED`, `REJECTED`
customerRole	`enum`	Customer role (`CLAIMANT`)
deadlineAt	`date`	Deadline date to filter
createdAt	`date`	Creation date to filter

Response

The status code 200 indicates successful query.

If the query is successful, the response will have the following fields in JSON format:

 [
    {
      "disputeId": "DSP123456789",
      "endToEndId": "E38224857202501011234567890123456",
      "disputeType": "SUSPECTED_FRAUD",
      "status": "PENDING",
      "customerRole": "CLAIMANT",
      "createdAt": "2025-01-01T10:30:00.000Z",
      "deadlineAt": "2025-01-15T23:59:59.999Z"
    },
    {
      "disputeId": "DSP987654321",
      "endToEndId": "E38224857202501019876543210987654",
      "disputeType": "OPERATIONAL_FAILURE",
      "status": "AWAITING_EVIDENCE",
      "customerRole": "CLAIMANT",
      "createdAt": "2024-12-28T15:45:00.000Z",
      "deadlineAt": "2025-01-12T23:59:59.999Z"
    }
  ]

Create dispute request​

Request​

Headers​

Body Parameters​

Response​

Cancel dispute​

Request​

Headers​

Path Parameters:​

Body​

Response​

Get specific dispute​

Request​

Headers​

Path Parameters:​

Response​

List disputes​

Request​

Headers​

Query Parameters:​

Response​

Create dispute request

Request

Headers

Body Parameters

Response

Cancel dispute

Request

Headers

Path Parameters:

Body

Response

Get specific dispute

Request

Headers

Path Parameters:

Response

List disputes

Request

Headers

Query Parameters:

Response