Overview

The Chargeback API is a communication channel between the platform and merchants with assigned disputes. It allows merchants to:

• List disputes assigned to them
• View dispute details
• View dispute history and audit trail
• Contest (submit a challenge) or accept a dispute
• Upload supporting documents (evidence)
• Download or list previously uploaded documents

The API is designed for secure, auditable exchanges and supports pagination, filtering, and role-based access.

Actors & Permissions

• Merchant - Can access disputes assigned to their merchant account; can contest, accept, and upload documents.
• Platform - For internal use: assign disputes, change statuses, and resolve disputes.
• Auditor - Read-only access for compliance teams (optional).

Common concepts & enums

Dispute Status

• Dispute Won = The merchant won the dispute, and any chargeback debit is reversed.
• Dispute Lost = The merchant lost the dispute, and the chargeback amount will be debited from the merchant’s account.
• Dispute Partially Won = The merchant lost the dispute, but the chargeback amount will not be fully debited from the merchant’s account.
• Needs Response = The merchant must send the required documents or accept the chargeback.
• In Review = The response is being validated by the Getnet network.

Merchant Status

• documentation_reproved = The PagoNxt team determined that the uploaded documents cannot be used as valid evidence.
• merchant_notified = The merchant has been notified that a response is required.
• verification_required = The required documents have been provided and are pending verification.
• chargeback_accepted = There are no pending actions on the merchant’s side, as the chargeback has been accepted.

Cycles

• retrieval_request = A retrieval request occurs when the card issuer requests additional information about a transaction before initiating a chargeback.
• retrieval_fulfillment = The merchant’s response to a retrieval request. It includes all documents and notes submitted to satisfy the issuer’s inquiry.
• first_chargeback = A first chargeback (also known as an initial chargeback) occurs when the issuer or cardholder disputes a transaction, and the funds may be debited from the merchant’s account.
• second_representment = The second presentment (also known as representment) is the merchant’s formal response to a first chargeback. The merchant submits evidence to the acquirer, who forwards it to the issuer for review. If accepted, the chargeback is reversed; if rejected, it may proceed to pre-arbitration.
• pre_arbitration = Occurs when the issuer disagrees with the merchant’s second presentment. It is the issuer’s opportunity to reopen the dispute before escalating it to card network arbitration.
• arbitration_chargeback = The final stage of the dispute process, where the card network makes a binding decision. At this point, both parties have submitted evidence, and the network rules in favor of either the issuer or the merchant. This decision is final and non-reversible.

Access credentials

To obtain API credentials, please contact your Account Manager for guidance. Your Account Manager will provide the necessary instructions andd assist you with the onboarding and credential gerenation process including your client_id and client_secret.

Authentication & Authorization

Flow

1. The merchant (or platform client) authenticates using the OAuth 2.0 client credentials flow.
2. The platform issues a bearer access token with a specific scope.
3. Every subsequent request to the API must include the Authorization header with the token

Example Authentication Flow

1. Obtain an access token from /oauth2/access_token
2. Use the token in all subsequent API call as Authorization: Bearer <access_token>
3. The token expires after 1 hour. Use the refresh token if available.

Security & Compliance

• All endpoints require HTTPS (TLS 1.2+).
• Access is controlled by OAuth2 scopes and merchant ownership
• Evidence files are stored encrypted at rest
• All actions are logged for audit
• Compliance with PCI-DSS, GDPR and LGPD standards