Header

Overview

Chargeback disputes are the last chance for a merchant to recover revenue loss after a chargeback has been filed against it.

The merchant has the opportunity to provide compelling evidence that proves the legitimacy of transactions claimed to be inappropriate by customers. If the evidence is adjudged to be strong enough, the merchant can keep the revenue despite the chargeback.

1. Objective

This documentation intends to help Merchant developers integrate to the PPRO Chargeback Disputes API, by describing the operations available with examples of requests and responses.

2. Dispute Process

2.1. General flow

The dispute process starts when a customer complains to an issuer about a transaction. Reasons for complaint vary and include, but are not limited to, fraud and consumer disputes. The issuer reports the chargeback claim to the acquirer, who then opens a case for dispute. PPRO shares the case information with the merchant, who can decide to dispute it or accept the chargeback. To start a dispute, the merchant submits compelling evidence to PPRO, who forwards it to the acquirer and issuer. If the issuer decides in favor of the merchant, the chargeback is not deducted from the merchant’s funds. On the other side, if the issuer decides in favor of the customer, the chargeback is discounted from the merchant’s funds and returned to the customer.

For the moment, disputes are enabled only in Brazil.

chargeback disputes flow

2.2. When to dispute

The merchant should accept a chargeback when:

  • the transaction is known to be fraudulent;

  • the evidence is not compelling enough;

  • the chargeback amount doesn’t compensate the effort to gather compelling evidence;

  • the merchant failed to refund the customer before the chargeback date.

The merchant should dispute a chargeback when:

  • there is strong evidence to support the case;

  • the chargeback amount is significant.

Disputes which involve transactions already refunded before the chargeback was created will be automatically disputed by PPRO on behalf of the merchant.

2.3. Timeline

The timeline of a dispute in Brazil is the following.

Event Limit Calendar Days

Issuer reporting a chargeback

365 days from transaction date

Merchant responding to dispute

9 days from chargeback reception date

Issuer analyzing and deciding a dispute

120 days from response date

Issuer deducting a disputed chargeback

365 days from response date

The vast majority of the chargebacks deducted are discounted during the period of analysis and decision by the issuer. Surpassing this period without a chargeback being deducted is a great indication of having potentially won the dispute.

2.4. Case Status

Each chargeback available for dispute can go through some of the following statuses.

case status flow
Status Description

NEW

It is the first status attributed to a newly-received case. It means the chargeback is available to be disputed.

ACCEPTED

If the merchant decides not to dispute and successfully submits an Accept request, then the case receives status ACCEPTED. It means that the chargeback will no longer be available for dispute.

EXPIRED

If the case reaches its response due date without a response from the merchant, its status will be automatically updated to EXPIRED. It means that the chargeback will no longer be available for dispute.

DISPUTED

If the merchant decides to dispute and successfully submits a Dispute request, then the case receives status DISPUTED. It means that evidence was submitted for analysis by the issuer.

AWAITING_RESOLUTION

If the merchant’s submitted Dispute request is acknowledged by the acquirer, then the case receives status AWAITING_RESOLUTION. It means that the acquirer is now aware of the Dispute, and it is analysing it to determine if the case will be WON or LOST.

LOST

If a chargeback is deducted by the acquirer, the status of the corresponding case is automatically updated to LOST. It means that the evidence, if provided, was insufficient and the chargeback amount was deducted.

WON

If no chargeback is deducted by the acquirer after analysis period, the status of the corresponding case is automatically updated to WON. It means that the evidence provided was sufficient and the Dispute was won.

Status WON would correspond to cases that had no chargebacks deducted. Nevertheless, this status is not available in the current version of the API. Cases in this situation will remain indefinitely with previous status (DISPUTED, ACCEPTED or EXPIRED).

2.5. API Status Codes

List of status and error codes that can be returned by the API.

API CODES DESCRIPTION

SUCCESS

Any operation on the API that was successful.

CASE_NOT_FOUND

Case not found on our database. Invalid id.

CASE_ALREADY_EXPIRED

Tried to dispute a case that already has status expired.

CASE_ALREADY_DISPUTED

Tried to dispute a case that already has status disputed.

CASE_ALREADY_LOST

Tried to dispute a case that already has status lost.

VALIDATION_ERROR

Invalid request parameters or body.

FILES_MISSING

When trying to DISPUTE case, but not providing the required files.

FILES_EXCEEDS_LIMIT_SIZE

When trying to DISPUTE case, but sending files that exceed the size limits.

FILES_INVALID_EXTENSION

When trying to DISPUTE case, but sending files that extensions are not supported.

INTERNAL_ERROR

Any unexpected internal exception.

2.6. Compelling Evidence

The quality of the evidence presented in the support documentation is directly related to the chances of success of a dispute. The merchant must prove that the cardholder participated in the transaction or benefitted from it. The recommended items to be submitted as evidence are listed below. In addition, merchants can send any other documentation that may be relevant to testify to the legitimacy of a transaction.

Section Information required Description Fraud Commercial Disagreement

Customer identification

Personal details

Customer name, cardholder name, tax id (CPF or CNPJ), email, telephone number, postal address.

X

X

Registration steps

Screenshots from mandatory fields in customer registration at merchant website.

X

X

Connection with cardholder

Evidence of relationship between the customer and the cardholder, if not the same person.

X

X

Purchase history

Transaction receipt

Document that formalizes the purchase including merchant details, customer details, items purchased, prices and payment method details.

X

X

Checkout

Screenshots from mandatory checkboxes and selection of payment method at merchant checkout page.

X

X

Evidence of use of product or service

Details of method for sharing product keys or download codes. Evidence of use, such as dates of downloads, recent access to the platform or similar.

X

X

Registration in the Customer Service Center

Evidence of recent interaction, if any, between customer and customer support team through available channels, including topic discussed.

X

X

Previous purchases

Summary of currently disputed purchase vs past non-disputed purchases from the same card number, including purchased products, dates and amount.

X

X

Terms and conditions

Automatic renewal policy

Summary of terms and conditions that authorize automatic renewal charges, followed by link with full policy.

X

Notification of renewal

Evidence of notification to customer about automatic renewal charge.

X

Cancellation of automatic renewal

Description of steps required for customer to deactivate automatic renewal option.

X

Refund conditions

Summary of refund policy for related products, followed by link to full policy.

X

Support channels for refund request

Contact details for customers to reach customer support channels.

X

General terms of use

Summary of terms and conditions that define user rights, followed by link to full policy.

X
The evidence can be provided in multiple files as long as the total size limit of 7MB is respected. Acceptable file extensions are PNG, JPG and PDF.
Preferably, the evidence would be presented in local language. If this is not possible, it should be presented in English.
Special attention should be given to the readability of screenshots in the documentation. Low resolution can prevent the delivery of critical information to the issuer.

3. Hosts

Environment Endpoints

TEST

https://test-chargebackdispute.ppro.com/

PRODUCTION

https://chargebackdispute.ppro.com/

To perform an operation, combine one of the hosts, from the expected environment with the endpoint of the desired operation and send it using the HTTP VERB as described in the operation.

It is necessary to contact PPRO to retrieve credentials for TEST and PRODUCTION. It can be done by e-mailing: merchant@ppro.com.

4. HTTP Verbs

We intend to get as close as possible to standard HTTP and REST conventions in the use of HTTP verbs.

Verb Usage

GET

Used to retrieve resources.

POST

Used to add a child resource under resources collection, it is a non-idempotent operation also commonly used to retrieve tokens.

PATCH

Used to partially update an existing resource, it is a non-idempotent operation.

5. Authentication API

The Authentication(s) API is used to handle all operations over a Case.

5.1. Get Token

POST /security/auth/realms/ppro/protocol/openid-connect/token

Gets a token from our authorization entity.

5.1.1. Request Body

Path Type Optional Description

client_id

String

false

Fixed value chargeback-disputes-api.

username

String

false

User name provided for authentication.

password

String

false

Password provided for authentication.

grant_type

String

false

Fixed value password.

5.1.2. Response fields

Path Type Optional Description

access_token

String

false

The token to be used to the following requests.

expires_in

String

false

Token time to live.

refresh_expires_in

String

true

Refresh token time to live.

refresh_token

String

true

Used in cases where the client of the token exchange needs the ability to access a resource even when the original credential is no longer valid (e.g., user-not-present or offline scenarios where there is no longer any user entertaining an active session with the client).

token_type

String

false

Type of the token. It’s typically "Bearer".

not-before-policy

Timestamp

true

Not-before policy ensures that any tokens issued before that time become invalid. It returns 0 if there was no not-before policy pushed.

session_state

String

true

JSON string that represents the End-User’s login state at the OpenId Provider.

scope

String

true

Scope of the access token issued.

5.1.3. Example request

POST /security/auth/realms/ppro/protocol/openid-connect/token HTTP/1.1
Host: test-chargebackdispute.ppro.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Content-Length: 99

client_id=chargeback-disputes-api&username=exampleuser&password=examplepassword&grant_type=password

5.1.4. Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 1966

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhY3IiOiIxIiwiYXpwIjoiY2hhcmdlYmFjay1kaXNwdXRlcy1hcGkiLCJleHAiOjE2MDQ5Mjk4MTYsImlhdCI6MTYwNDkyOTUxNiwiaXNzIjoiaHR0cHM6Ly9zdGFnaW5nLXBwcm8ta2V5Y2xvYWstc2VydmljZS5hbGxwYWdvLmNvbS9wcHJvLWtleWNsb2FrLXNlcnZpY2UvYXV0aC9yZWFsbXMvcHBybyIsImp0aSI6IjliZWJjNmM1LTZlNTYtNDVhMS05ZDkwLTRiYTA5ZjlhZjNhMCIsIm9yZ2FuaXphdGlvbiI6ImV4YW1wbGUub3JnYW5pemF0aW9uIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiZXhhbXBsZS51c2VyIiwic2NvcGUiOiJwcm9maWxlIiwic2Vzc2lvbl9zdGF0ZSI6ImQyZWZhNzM3LWM4NzAtNGUwOC1hMDA3LWFhZjg4YzcyODMyOCIsInN1YiI6ImQyZWZhNzM3LWM4NzAtNGUwOC1hMDA3LWFhZjg4YzcyODMyOCIsInR5cCI6IkJlYXJlciJ9.y5jLb7fdkQqPN2uHM28x18xRhyOrAaIaEvLD5nZOwcwgFRiprn9Gw60ZbLLPuA1Mo0VAD056w2EPO9cNkq6LVB-aNo9u5SDOnG65fglbY1Zf4cGjqEwfjvlwd66KaCYEkIEyjdxTbX4OceawA8q5IiI8AvNjJLDr8mK1_k0lOrglpPXQm77-wZkjbg2b-AUr_LM0JVOEB28XYuC3X4ZQzTfyj7UIB4UT7sFmPtda3nZXbHBisg6Rz-hurdfUp2lm4hNfrFDaqGB1fWlbF_at-CPB7deN55EuRJISu8lkYXAKShHlSfqkDhyDWD9xTh0fH77ErFstoy3_L7bPvMyImlXD4bE_8Ei-9uGiusf5dUL1IMieJwZnRio1PRQDZRKd50awFvL94i72EV4WwdxbsaXJXxIItK11JZuNrep0NxfWi42wHWT5XpnZ52ExzWRQ1h9rKn1H073wnKGd9qnvJ_lJQWr4D1RzM6nmDvHiQcC4v26Tk96R2rsENlU_dNSg",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJodHRwczovL3N0YWdpbmctcHByby1rZXljbG9hay1zZXJ2aWNlLmFsbHBhZ28uY29tL3NlY3VyaXR5L2F1dGgvcmVhbG1zL3Bwcm8iLCJhenAiOiJjaGFyZ2ViYWNrLWRpc3B1dGVzLWFwaSIsImV4cCI6MTYwNDkzMTMxNiwiaWF0IjoxNjA0OTI5NTE2LCJpc3MiOiJodHRwczovL3N0YWdpbmctcHByby1rZXljbG9hay1zZXJ2aWNlLmFsbHBhZ28uY29tL3NlY3VyaXR5L2F1dGgvcmVhbG1zL3Bwcm8iLCJqdGkiOiI1MDRiZTY4NC1jNjk3LTQzMmYtYTE5OC0zZmMyMTdkOTRmNTIiLCJzY29wZSI6InByb2ZpbGUiLCJzZXNzaW9uX3N0YXRlIjoiYzEwZmVlZDAtNGQ3MS00YzMyLTk2MjYtZmQ2ZmQyYmEyMDYwIiwic3ViIjoiM2U0N2M2NDItNjczYi00YWM0LWExMTktNzA5OGEzNTgwMTBmIiwidHlwIjoiUmVmcmVzaCJ9.lmJsqnhOsJkrWYMESV3et1L8yUEdIHj-sD-dO5qoHbDQr08Cc_hHOkKStd9lIyvCRvZ5xZ5wJF3E1XL-8YF3mC6EIwjHy3g4VvBlPTm-Jnbq3Yz1WAzrcgPs8xjO-WQzsZJ3F1HIqoPEhHwCr3VHlKIEviawiI5ZKoLTtoqpKn5WCnM3JRKPgzFH8q5pgqo513t5HwLZfiLrE1H9VDdhj9p3oPILvWIkcGLC-5MO3KaBGpQu3sDuwJ5KOT5h1HRKn4vZrLWUFKipuzQfgaJJKfIVSnhC7hglYmXXOwxzbijz8P3Gy5n-9-M-NiwX92VWWW3Eg1fmXlhGHMOl8ngKcVYKL1naBqoZRIXAIeS2S2_xblHRLAU3mE_2FVcgzK7BV2okqNf587lInDhxtYZMMMe2s8e0wMAhZxQZNKdnZCeq5NRjqxgYTqcKl-BPbIX-_Rhv4TkZnFVDSlNhsQz5FKLX7hYndmjXyYBxEpFjJlJ08DWYS1Hm6xJzX4xVp2HZ",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "6409f39a-d1a1-4068-9324-f4bf6c2c7adf",
    "scope": "profile"
}

6. Case(s) API

The Case(s) API is used to handle all operations over a Case. The Cases available for dispute can be simply ACCEPTED or DISPUTED by the Merchant.

It is important to know that after a period of 9 days from the reception date, the Case will be set as EXPIRED.

6.1. Get Case

GET /api/v1/cases/{id}

6.1.1. Path parameters

Parameter Type Optional Description

id

Object

false

6.1.2. Response fields

Path Type Optional Description

id

String

false

receptionDate

String

false

responseDueDate

String

false

responseDate

String

true

chargebackAmount

Decimal

false

Must be at least 0.0.
Must be at most 10000000000.

reasonCode

String

true

fraud

Boolean

true

currency

String

false

Size must be equal to 3.

lastUpdateDate

String

false

status

String

false

Must be one of [NEW, ACCEPTED, DISPUTED, AWAITING_RESOLUTION, EXPIRED, LOST, WON].

merchant

Object

true

merchant.name

String

true

merchant.transactionId

String

false

submerchant

Object

true

submerchant.name

String

true

transaction

Object

true

transaction.uuid

String

true

transaction.id

String

true

transaction.date

String

true

transaction.cardNumber

String

true

transaction.brand

String

true

transaction.descriptor

String

true

transaction.amount

Decimal

false

Must be at least 0.0.
Must be at most 10000000000.

statuses

Array[Object]

false

statuses[].status

String

false

Must be one of [NEW, ACCEPTED, DISPUTED, AWAITING_RESOLUTION, EXPIRED, LOST, WON].

statuses[].date

String

false

6.1.3. Example request

GET /api/v1/cases/df071f04-9ef4-41c9-a7b3-cb302a73c1b3 HTTP/1.1
Content-Type: application/json
Host: test-chargebackdispute.ppro.com

6.1.4. Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 830

{
  "id" : "df071f04-9ef4-41c9-a7b3-cb302a73c1b3",
  "receptionDate" : "2025-11-28T11:32:42.409396",
  "responseDueDate" : "2026-01-11T11:32:42.409396",
  "responseDate" : "2025-12-18T11:32:42.409396",
  "chargebackAmount" : 10000.0,
  "reasonCode" : "2189",
  "fraud" : false,
  "currency" : "BRL",
  "lastUpdateDate" : "2025-12-28T11:32:42.409396",
  "status" : "NEW",
  "merchant" : {
    "name" : "adobe",
    "transactionId" : "36c0764c-8ed6-4c2c-919a-dfce4e0d4c2a"
  },
  "submerchant" : { },
  "transaction" : {
    "uuid" : "2dd42c8d-af35-48f1-b88e-ebab031cbe08",
    "date" : "2025-12-03T11:32:42.409451",
    "cardNumber" : "445512******3456",
    "brand" : "Visa",
    "descriptor" : "Product 0001",
    "amount" : 10000.35
  },
  "statuses" : [ {
    "status" : "NEW",
    "date" : "2025-12-28T11:32:42.409396"
  } ]
}

6.2. Get Cases

GET /api/v1/cases

6.2.1. Query parameters

Parameter Type Optional Description

from

Object

false

Must be in the past or the present.

to

Object

true

dateCriterion

String

true

Must be one of [RECEPTION_DATE, RESPONSE_DUE_DATE, RESPONSE_DATE, LAST_UPDATE_DATE].Default value: 'RECEPTION_DATE'.

statuses

Object

true

Must be one of [NEW, ACCEPTED, DISPUTED, AWAITING_RESOLUTION, EXPIRED, LOST, WON].Default value: 'NEW'.

page

Integer

true

Must be at least 0 and at most 2147483647.Default value: '0'.

size

Integer

true

Must be at least 1 and at most 2000.Default value: '500'.

6.2.2. Response fields

Path Type Optional Description

numberOfElements

Integer

true

page

Integer

true

hasNext

Boolean

true

content

Array[Object]

true

content[].id

String

false

content[].receptionDate

String

false

content[].responseDueDate

String

false

content[].responseDate

String

true

content[].chargebackAmount

Decimal

false

Must be at least 0.0.
Must be at most 10000000000.

content[].reasonCode

String

true

content[].fraud

Boolean

true

content[].currency

String

false

Size must be equal to 3.

content[].lastUpdateDate

String

false

content[].status

String

false

Must be one of [NEW, ACCEPTED, DISPUTED, AWAITING_RESOLUTION, EXPIRED, LOST, WON].

content[].merchant

Object

true

content[].merchant.name

String

true

content[].merchant.transactionId

String

false

content[].submerchant

Object

true

content[].submerchant.name

String

true

content[].transaction

Object

true

content[].transaction.uuid

String

true

content[].transaction.id

String

true

content[].transaction.date

String

true

content[].transaction.cardNumber

String

true

content[].transaction.brand

String

true

content[].transaction.descriptor

String

true

content[].transaction.amount

Decimal

false

Must be at least 0.0.
Must be at most 10000000000.

content[].statuses

Array[Object]

false

content[].statuses[].status

String

false

Must be one of [NEW, ACCEPTED, DISPUTED, AWAITING_RESOLUTION, EXPIRED, LOST, WON].

content[].statuses[].date

String

false

6.2.3. Example request

GET /api/v1/cases?from=2025-12-28&to=2025-12-28&dateCriterion=LAST_UPDATE_DATE&statuses=NEW&page=0&size=100 HTTP/1.1
Content-Type: application/json
Host: test-chargebackdispute.ppro.com

6.2.4. Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 2746

{
  "content" : [ {
    "id" : "9b15c89d-a7ab-4b9d-8404-a7036fe79114",
    "receptionDate" : "2025-12-25T11:32:40.945681",
    "responseDueDate" : "2026-01-11T11:32:40.945681",
    "responseDate" : "2025-12-18T11:32:40.945681",
    "chargebackAmount" : 10000.0,
    "reasonCode" : "2189",
    "fraud" : false,
    "currency" : "BRL",
    "lastUpdateDate" : "2025-12-28T11:32:40.945681",
    "status" : "NEW",
    "merchant" : {
      "name" : "adobe",
      "transactionId" : "e82bdab4-5909-4c41-9107-b7ce2f2b4b5d"
    },
    "submerchant" : { },
    "transaction" : {
      "uuid" : "9b15c89d-a7ab-4b9d-8404-a7036fe79114",
      "date" : "2025-12-03T11:32:40.945753",
      "cardNumber" : "445512******3456",
      "brand" : "Visa",
      "descriptor" : "Product 0001",
      "amount" : 10000.35
    },
    "statuses" : [ {
      "status" : "NEW",
      "date" : "2025-12-28T11:32:40.945681"
    } ]
  }, {
    "id" : "64285eac-a048-459a-ae78-f1661fae1c3d",
    "receptionDate" : "2025-12-25T11:32:40.945681",
    "responseDueDate" : "2026-01-11T11:32:40.945681",
    "responseDate" : "2025-12-18T11:32:40.945681",
    "chargebackAmount" : 10000.0,
    "reasonCode" : "2189",
    "fraud" : false,
    "currency" : "BRL",
    "lastUpdateDate" : "2025-12-28T11:32:40.945681",
    "status" : "NEW",
    "merchant" : {
      "name" : "adobe",
      "transactionId" : "97e928b2-ca03-4c7c-8150-cfb1b4c7639e"
    },
    "submerchant" : { },
    "transaction" : {
      "uuid" : "64285eac-a048-459a-ae78-f1661fae1c3d",
      "date" : "2025-12-03T11:32:40.950692",
      "cardNumber" : "445512******3456",
      "brand" : "Visa",
      "descriptor" : "Product 0001",
      "amount" : 10000.35
    },
    "statuses" : [ {
      "status" : "NEW",
      "date" : "2025-12-28T11:32:40.945681"
    } ]
  }, {
    "id" : "005d7c0d-ea7e-405f-855d-885dc12b8729",
    "receptionDate" : "2025-12-25T11:32:40.945681",
    "responseDueDate" : "2026-01-11T11:32:40.945681",
    "responseDate" : "2025-12-18T11:32:40.945681",
    "chargebackAmount" : 10000.0,
    "reasonCode" : "2189",
    "fraud" : false,
    "currency" : "BRL",
    "lastUpdateDate" : "2025-12-28T11:32:40.945681",
    "status" : "NEW",
    "merchant" : {
      "name" : "adobe",
      "transactionId" : "aa44b0ae-a4b4-4857-b195-1299dc523d8d"
    },
    "submerchant" : { },
    "transaction" : {
      "uuid" : "005d7c0d-ea7e-405f-855d-885dc12b8729",
      "date" : "2025-12-03T11:32:40.952295",
      "cardNumber" : "445512******3456",
      "brand" : "Visa",
      "descriptor" : "Product 0001",
      "amount" : 10000.35
    },
    "statuses" : [ {
      "status" : "NEW",
      "date" : "2025-12-28T11:32:40.945681"
    } ]
  } ],
  "page" : 0,
  "hasNext" : false,
  "numberOfElements" : 20
}

6.3. Accept Case

PATCH /api/v1/cases/{id}/accept

6.3.1. Path parameters

Parameter Type Optional Description

id

Object

false

6.3.2. Response fields

Path Type Optional Description

id

String

false

receptionDate

String

false

responseDueDate

String

false

responseDate

String

true

chargebackAmount

Decimal

false

Must be at least 0.0.
Must be at most 10000000000.

reasonCode

String

true

fraud

Boolean

true

currency

String

false

Size must be equal to 3.

lastUpdateDate

String

false

status

String

false

Must be one of [NEW, ACCEPTED, DISPUTED, AWAITING_RESOLUTION, EXPIRED, LOST, WON].

merchant

Object

true

merchant.name

String

true

merchant.transactionId

String

false

submerchant

Object

true

submerchant.name

String

true

transaction

Object

true

transaction.uuid

String

true

transaction.id

String

true

transaction.date

String

true

transaction.cardNumber

String

true

transaction.brand

String

true

transaction.descriptor

String

true

transaction.amount

Decimal

false

Must be at least 0.0.
Must be at most 10000000000.

statuses

Array[Object]

false

statuses[].status

String

false

Must be one of [NEW, ACCEPTED, DISPUTED, AWAITING_RESOLUTION, EXPIRED, LOST, WON].

statuses[].date

String

false

6.3.3. Example request

PATCH /api/v1/cases/bbbf7b34-090c-4de1-b0de-62c2f63d93f5/accept HTTP/1.1
Content-Type: application/json
Content-Length: 1111
Host: test-chargebackdispute.ppro.com

[{"name":"my-file","extension":"PNG","binaryBase64":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="},{"name":"my-file","extension":"PDF","binaryBase64":"JVBERi0xLjcKCjEgMCBvYmogICUgZW50cnkgcG9pbnQKPDwKICAvVHlwZSAvQ2F0YWxvZwogIC9QYWdlcyAyIDAgUgo+PgplbmRvYmoKCjIgMCBvYmoKPDwKICAvVHlwZSAvUGFnZXMKICAvTWVkaWFCb3ggWyAwIDAgMjAwIDIwMCBdCiAgL0NvdW50IDEKICAvS2lkcyBbIDMgMCBSIF0KPj4KZW5kb2JqCgozIDAgb2JqCjw8CiAgL1R5cGUgL1BhZ2UKICAvUGFyZW50IDIgMCBSCiAgL1Jlc291cmNlcyA8PAogICAgL0ZvbnQgPDwKICAgICAgL0YxIDQgMCBSIAogICAgPj4KICA+PgogIC9Db250ZW50cyA1IDAgUgo+PgplbmRvYmoKCjQgMCBvYmoKPDwKICAvVHlwZSAvRm9udAogIC9TdWJ0eXBlIC9UeXBlMQogIC9CYXNlRm9udCAvVGltZXMtUm9tYW4KPj4KZW5kb2JqCgo1IDAgb2JqICAlIHBhZ2UgY29udGVudAo8PAogIC9MZW5ndGggNDQKPj4Kc3RyZWFtCkJUCjcwIDUwIFRECi9GMSAxMiBUZgooSGVsbG8sIHdvcmxkISkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iagoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDEwIDAwMDAwIG4gCjAwMDAwMDAwNzkgMDAwMDAgbiAKMDAwMDAwMDE3MyAwMDAwMCBuIAowMDAwMDAwMzAxIDAwMDAwIG4gCjAwMDAwMDAzODAgMDAwMDAgbiAKdHJhaWxlcgo8PAogIC9TaXplIDYKICAvUm9vdCAxIDAgUgo+PgpzdGFydHhyZWYKNDkyCiUlRU9G"}]

6.3.4. Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 906

{
  "id" : "bbbf7b34-090c-4de1-b0de-62c2f63d93f5",
  "receptionDate" : "2025-12-23T11:32:41.16136",
  "responseDueDate" : "2026-01-11T11:32:41.161373",
  "responseDate" : "2026-01-02T11:32:41.20298",
  "chargebackAmount" : 10000.0,
  "reasonCode" : "2189",
  "fraud" : false,
  "currency" : "BRL",
  "lastUpdateDate" : "2026-01-02T11:32:41.20298",
  "status" : "ACCEPTED",
  "merchant" : {
    "name" : "adobe",
    "transactionId" : "1065e552-f5a5-4313-b607-4b72cf4942be"
  },
  "submerchant" : { },
  "transaction" : {
    "uuid" : "34513627-e13a-499a-919d-1d1adf48cbe9",
    "date" : "2025-12-03T11:32:41.161438",
    "cardNumber" : "445512******3456",
    "brand" : "Visa",
    "descriptor" : "Product 0001",
    "amount" : 10000.35
  },
  "statuses" : [ {
    "status" : "NEW",
    "date" : "2025-12-23T11:32:41.16136"
  }, {
    "status" : "ACCEPTED",
    "date" : "2026-01-02T11:32:41.20298"
  } ]
}

6.4. Dispute Case

PATCH /api/v1/cases/{id}/dispute

6.4.1. Path parameters

Parameter Type Optional Description

id

Object

false

6.4.2. Request fields

Path Type Optional Description

[].name

String

false

[].extension

String

false

Must be one of [PNG, JPG, PDF, TIFF].

[].binaryBase64

Array[Integer]

false

6.4.3. Response fields

Path Type Optional Description

id

String

false

receptionDate

String

false

responseDueDate

String

false

responseDate

String

true

chargebackAmount

Decimal

false

Must be at least 0.0.
Must be at most 10000000000.

reasonCode

String

true

fraud

Boolean

true

currency

String

false

Size must be equal to 3.

lastUpdateDate

String

false

status

String

false

Must be one of [NEW, ACCEPTED, DISPUTED, AWAITING_RESOLUTION, EXPIRED, LOST, WON].

merchant

Object

true

merchant.name

String

true

merchant.transactionId

String

false

submerchant

Object

true

submerchant.name

String

true

transaction

Object

true

transaction.uuid

String

true

transaction.id

String

true

transaction.date

String

true

transaction.cardNumber

String

true

transaction.brand

String

true

transaction.descriptor

String

true

transaction.amount

Decimal

false

Must be at least 0.0.
Must be at most 10000000000.

statuses

Array[Object]

false

statuses[].status

String

false

Must be one of [NEW, ACCEPTED, DISPUTED, AWAITING_RESOLUTION, EXPIRED, LOST, WON].

statuses[].date

String

false

6.4.4. Example request

PATCH /api/v1/cases/762cc668-4399-4e56-b0bd-8755fa85dc0b/dispute HTTP/1.1
Content-Type: application/json
Content-Length: 1111
Host: test-chargebackdispute.ppro.com

[{"name":"my-file","extension":"PNG","binaryBase64":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="},{"name":"my-file","extension":"PDF","binaryBase64":"JVBERi0xLjcKCjEgMCBvYmogICUgZW50cnkgcG9pbnQKPDwKICAvVHlwZSAvQ2F0YWxvZwogIC9QYWdlcyAyIDAgUgo+PgplbmRvYmoKCjIgMCBvYmoKPDwKICAvVHlwZSAvUGFnZXMKICAvTWVkaWFCb3ggWyAwIDAgMjAwIDIwMCBdCiAgL0NvdW50IDEKICAvS2lkcyBbIDMgMCBSIF0KPj4KZW5kb2JqCgozIDAgb2JqCjw8CiAgL1R5cGUgL1BhZ2UKICAvUGFyZW50IDIgMCBSCiAgL1Jlc291cmNlcyA8PAogICAgL0ZvbnQgPDwKICAgICAgL0YxIDQgMCBSIAogICAgPj4KICA+PgogIC9Db250ZW50cyA1IDAgUgo+PgplbmRvYmoKCjQgMCBvYmoKPDwKICAvVHlwZSAvRm9udAogIC9TdWJ0eXBlIC9UeXBlMQogIC9CYXNlRm9udCAvVGltZXMtUm9tYW4KPj4KZW5kb2JqCgo1IDAgb2JqICAlIHBhZ2UgY29udGVudAo8PAogIC9MZW5ndGggNDQKPj4Kc3RyZWFtCkJUCjcwIDUwIFRECi9GMSAxMiBUZgooSGVsbG8sIHdvcmxkISkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iagoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDEwIDAwMDAwIG4gCjAwMDAwMDAwNzkgMDAwMDAgbiAKMDAwMDAwMDE3MyAwMDAwMCBuIAowMDAwMDAwMzAxIDAwMDAwIG4gCjAwMDAwMDAzODAgMDAwMDAgbiAKdHJhaWxlcgo8PAogIC9TaXplIDYKICAvUm9vdCAxIDAgUgo+PgpzdGFydHhyZWYKNDkyCiUlRU9G"}]

6.4.5. Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 908

{
  "id" : "762cc668-4399-4e56-b0bd-8755fa85dc0b",
  "receptionDate" : "2025-12-23T11:32:41.41023",
  "responseDueDate" : "2026-01-11T11:32:41.410244",
  "responseDate" : "2026-01-02T11:32:41.462832",
  "chargebackAmount" : 10000.0,
  "reasonCode" : "2189",
  "fraud" : false,
  "currency" : "BRL",
  "lastUpdateDate" : "2026-01-02T11:32:41.462832",
  "status" : "DISPUTED",
  "merchant" : {
    "name" : "adobe",
    "transactionId" : "7186d8e0-6de1-4ea1-a638-d31b48b5c987"
  },
  "submerchant" : { },
  "transaction" : {
    "uuid" : "3c7bfe2f-fbf9-4553-adda-b9f26c8a258a",
    "date" : "2025-12-03T11:32:41.41029",
    "cardNumber" : "445512******3456",
    "brand" : "Visa",
    "descriptor" : "Product 0001",
    "amount" : 10000.35
  },
  "statuses" : [ {
    "status" : "NEW",
    "date" : "2025-12-23T11:32:41.41023"
  }, {
    "status" : "DISPUTED",
    "date" : "2026-01-02T11:32:41.462832"
  } ]
}

6.5. Get Case Files

GET /api/v1/cases/{id}/files

6.5.1. Path parameters

Parameter Type Optional Description

id

Object

false

6.5.2. Response fields

No response body.

6.5.3. Example request

GET /api/v1/cases/f750d712-0624-419e-915b-926f93f65a42/files HTTP/1.1
Host: test-chargebackdispute.ppro.com

6.5.4. Example response

HTTP/1.1 200 OK
Content-Disposition: attachment; filename="f750d712-0624-419e-915b-926f93f65a42.zip"
Content-Type: application/zip
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

7. Playground Additional API

The Playground API is offered with an additional operation to create Cases for test purposes.

This entry point is ONLY available for testing.

7.1. Create Case

POST /api/v1/cases

7.1.1. Request fields

Path Type Optional Description

receptionDate

String

true

responseDueDate

String

true

chargebackAmount

Decimal

true

Must be at least 0.0.
Must be at most 10000000000.

reasonCode

String

true

fraud

Boolean

true

additionalData

String

true

currency

String

true

com.ppro.disputes.constraints.Iso4217Currency.

merchant

Object

true

merchant.transactionId

String

true

transaction

Object

true

transaction.date

String

true

transaction.cardNumber

String

true

transaction.brand

String

true

transaction.descriptor

String

true

transaction.amount

Decimal

true

Must be at least 0.0.
Must be at most 10000000000.

statuses

Array[Object]

true

statuses[].status

String

false

Must be one of [NEW, ACCEPTED, DISPUTED, AWAITING_RESOLUTION, EXPIRED, LOST, WON].

statuses[].date

String

false

7.1.2. Response fields

Path Type Optional Description

id

String

false

receptionDate

String

false

responseDueDate

String

false

responseDate

String

true

chargebackAmount

Decimal

false

Must be at least 0.0.
Must be at most 10000000000.

reasonCode

String

true

fraud

Boolean

true

currency

String

false

Size must be equal to 3.

lastUpdateDate

String

false

status

String

false

Must be one of [NEW, ACCEPTED, DISPUTED, AWAITING_RESOLUTION, EXPIRED, LOST, WON].

merchant

Object

true

merchant.name

String

true

merchant.transactionId

String

false

submerchant

Object

true

submerchant.name

String

true

transaction

Object

true

transaction.uuid

String

true

transaction.id

String

true

transaction.date

String

true

transaction.cardNumber

String

true

transaction.brand

String

true

transaction.descriptor

String

true

transaction.amount

Decimal

false

Must be at least 0.0.
Must be at most 10000000000.

statuses

Array[Object]

false

statuses[].status

String

false

Must be one of [NEW, ACCEPTED, DISPUTED, AWAITING_RESOLUTION, EXPIRED, LOST, WON].

statuses[].date

String

false

7.1.3. Example request

POST /api/v1/cases HTTP/1.1
Content-Type: application/json
Content-Length: 827
Host: test-chargebackdispute.ppro.com

{
  "id" : "1ebe6069-52b7-46ce-81d6-bb2d93e2a836",
  "receptionDate" : "2025-11-28T11:32:47.865472",
  "responseDueDate" : "2025-12-08T11:32:47.865472",
  "responseDate" : "2025-12-18T11:32:47.865472",
  "chargebackAmount" : 1E+4,
  "reasonCode" : "2189",
  "fraud" : false,
  "currency" : "BRL",
  "lastUpdateDate" : "2025-12-28T11:32:47.865472",
  "status" : "NEW",
  "merchant" : {
    "name" : "adobe",
    "transactionId" : "4e1a3617-cc7f-4994-b659-d689df23069c"
  },
  "submerchant" : { },
  "transaction" : {
    "uuid" : "1ebe6069-52b7-46ce-81d6-bb2d93e2a836",
    "date" : "2025-12-03T11:32:47.865487",
    "cardNumber" : "445512******3456",
    "brand" : "Visa",
    "descriptor" : "Product 0001",
    "amount" : 10000.35
  },
  "statuses" : [ {
    "status" : "NEW",
    "date" : "2025-12-28T11:32:47.865472"
  } ]
}

7.1.4. Example response

HTTP/1.1 201 Created
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 833

{
  "id" : "045fe6c7-270a-4e1e-add1-b5317154f5cb",
  "receptionDate" : "2025-11-28T11:32:47.865472",
  "responseDueDate" : "2025-12-08T11:32:47.865472",
  "chargebackAmount" : 10000.0,
  "reasonCode" : "2189",
  "fraud" : false,
  "currency" : "BRL",
  "lastUpdateDate" : "2025-12-28T11:32:47.865472",
  "status" : "NEW",
  "merchant" : {
    "name" : "NortonLifeLock",
    "transactionId" : "4e1a3617-cc7f-4994-b659-d689df23069c"
  },
  "submerchant" : { },
  "transaction" : {
    "uuid" : "b442908e-0e4c-48d4-b578-03118f81e5a6",
    "id" : "charge_hj8IjgwVQKw40JKJsubId",
    "date" : "2025-12-03T11:32:47.865487",
    "cardNumber" : "445512******3456",
    "brand" : "Visa",
    "descriptor" : "Product 0001",
    "amount" : 10000.35
  },
  "statuses" : [ {
    "status" : "NEW",
    "date" : "2025-12-28T11:32:47.865472"
  } ]
}