Chargeback Management

1. Briefing

This API applies to integrated chargebacks across all markets where Getnet operates.

The Chargeback API is a communication channel between the platform and merchants that have disputes assigned to them. It offers a solution for handling disputes, allowing the merchants to manage chargebacks across all sellers from a single view.

It is possible to:

List disputes assigned to the merchant
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.

2. Common Concepts and Permissions

Chargeback: A dispute initiated by a customer through their issuing bank due to a transaction they find problematic, such as unauthorized payments, incorrect amounts, or merchant disputes.

Commercial dispute: A customer reverses a payment that was legitimately initiated. This typically happens when the customer disputes having received the goods (non-receipt) or argues the goods were defective/not as described. The merchant is required to provide evidence to challenge the reversal.

Fraud dispute (Friendly or Criminal): A malicious third party uses stolen or compromised payment instrument without the cardholder's knowledge to complete a transaction.

Merchant: Can access disputes assigned to their merchant account. Can contest, accept, and upload documents.

Platform: Internal use assign disputes, change statuses, resolve disputes.

Auditor: Read-only access for compliance teams (optional).

2.1 Dispute Status

dispute_status is the primary status of a dispute. It indicates whether there is a pending action required from the merchant, whether the dispute is under analysis by Getnet, or whether it has already reached a final outcome.

Status	Description
`needs_response`	Merchant must send the document or accept the chargeback.
`in_review`	Response being validated by Getnet Network.
`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 merchant.
`dispute_partially_won`	The merchant recovers funds corresponding to the portion proven valid. The cardholder receives a refund for the successfully disputed amount.

2.2 Merchant Status

merchant_status acts as a supporting status that provides additional context to the dispute_status. It categorizes the merchant's current position within the dispute

Status	Description
`merchant_notified`	The merchant has been notified that a response is needed.
`verification_required`	There are no pending issues on the merchant's side the necessary documents have been provided.
`documentation_reproved`	Getnet staff determined that the uploaded documents cannot be used as evidence.
`chargeback_accepted`	There are no pending issues on the merchant's side the chargeback has been accepted.

2.3 Cycles

Cycles represent the phases of a dispute lifecycle. All card brands have their stages normalized within the chargeback cycle structure below.

Cycle 0 Informational

Non-monetary phase. The issuer requests additional information before formally initiating a chargeback.

Status	Description
`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. Includes all documents and notes submitted to satisfy the issuer's inquiry. If the retrieval request remains unanswered or unresolved, the brand may escalate to a monetary cycle.

Cycle 1 Monetary (First Chargeback)

Monetary phase. Funds may be debited from the merchant.

Status	Description
`first_chargeback`	Occurs when the issuer or cardholder disputes a transaction and funds can be debited from the merchant.
`second_presentment`	The merchant's formal response to the first chargeback. The merchant submits evidence to the acquirer, who forwards it to the issuer for review.

Cycle 2 Monetary (Pre-Arbitration)

Monetary phase. The issuer re-opens the dispute after reviewing the merchant's representment.

Status	Description
`pre_arbitration`	Occurs when the issuer disagrees with the merchant's second presentment. Last opportunity before escalating to card network arbitration.
`pre_arbitration_response`	The merchant's response to the pre-arbitration. If unresolved, the dispute proceeds to final arbitration.

Cycle 3 Arbitration

Final stage. The card network makes a binding decision that is non-reversible.

Status	Description
`arbitration_chargeback`	The card network rules in favor of either party after reviewing all submitted evidence. This decision is final.

Cycle Progression and Finalization

A dispute can enter the lifecycle at two points: directly at Cycle 1 (most common) or at Cycle 0 when the issuer first requests supporting information.

Cycle	Type	Statuses	Possible Outcomes
Cycle 0	Informational	`retrieval_request` → `retrieval_fulfillment`	Resolved → `dispute_won` · Escalated → enters Cycle 1
Cycle 1	Monetary	`first_chargeback` → `second_presentment`	`dispute_won` · `dispute_lost` · `dispute_partially_won` · Escalated → enters Cycle 2
Cycle 2	Monetary	`pre_arbitration` → `pre_arbitration_response`	`dispute_won` · `dispute_lost` · `dispute_partially_won` · Escalated → enters Cycle 3
Cycle 3	Arbitration	`arbitration_chargeback`	`dispute_won` · `dispute_lost` · `dispute_partially_won`

Finalization statuses:

Status	Meaning
`dispute_won`	The merchant's contestation was accepted. Any chargeback debit is reversed. Can be reached at the end of Cycles 0, 1, 2, or 3.
`dispute_lost`	The dispute was ruled in favor of the cardholder. The chargeback amount is debited from the merchant. Can occur at Cycles 1, 2, or 3.
`dispute_partially_won`	A portion of the disputed amount is returned to the merchant; the remainder is awarded to the cardholder. Can occur from `second_presentment` (Cycle 1), `pre_arbitration`, `pre_arbitration_response` (Cycle 2), or `arbitration_chargeback` (Cycle 3).

Chargeback cycle evolution

3. Response Deadlines (SLA)

When a dispute is assigned to the merchant and requires action, the platform sets a response deadline based on the card network's internal timelines. In practice, the merchant typically has 15 calendar days from the moment of notification to submit a contestation or accept the chargeback.

The exact deadline for each dispute is available in the merchant_expiration_date field, returned by the following endpoints:

Endpoint	Where `merchant_expiration_date` appears
`GET /disputes`	Inside each item of the response list (`situation.merchant_expiration_date`)
`GET /disputes/{dispute_id}`	In the dispute detail response (`situation.merchant_expiration_date`)
`GET /disputes/{dispute_id}/cycles`	Per cycle record (`merchant_expiration_date`)

Always use merchant_expiration_date as the authoritative deadline — do not rely on a fixed 15-day window, as the actual deadline may vary by card brand, market, and dispute type.

3.1 Conditions to Respond to a Dispute

A dispute can only receive a merchant response (contestation or acceptance) when both conditions are met:

Condition	Description
`dispute_status = needs_response`	The dispute is in a state that requires merchant action. Any other status (e.g., `in_review`, `dispute_won`, `dispute_lost`) means the window has already closed or is not applicable.
`merchant_expiration_date` not yet passed	The response deadline has not expired. Once the current date exceeds `merchant_expiration_date`, the dispute can no longer be acted upon.

If either condition is not met, the following endpoints will return an error:

Endpoint	Action blocked after expiration or outside `needs_response`
`PATCH /disputes/{dispute_id}`	Accept the dispute — blocked
`POST /disputes/{dispute_id}/evidences`	Submit contestation — blocked

Important: Uploading documents via POST /disputes/{dispute_id}/documents may still be technically possible after the deadline, but those documents will have no effect if the contestation cannot be submitted. Always submit the contestation before merchant_expiration_date.

4. Chargeback API

The Payment Disputes API (Chargeback API) allows merchants integrated with Getnet to manage the full lifecycle of payment disputes programmatically without relying on manual backoffice processes. Using this API, you can monitor incoming chargebacks, upload supporting documents, request re-evaluations, accept disputes, and track each cycle's outcome in real time.

Available Endpoints

Method	Endpoint	Purpose
`GET`	`/reason-codes`	Lists all reason codes used by card brands to open disputes
`GET`	`/disputes`	Lists and filters disputes by date, brand, status, cycle, and more
`GET`	`/disputes/{dispute_id}`	Retrieves full details of a specific dispute
`PATCH`	`/disputes/{dispute_id}`	Accepts a dispute (merchant concedes the chargeback)
`POST`	`/disputes/{dispute_id}/evidences`	Submits previously uploaded documents as evidence for re-evaluation
`GET`	`/disputes/{dispute_id}/cycles`	Retrieves the full cycle history of a dispute
`POST`	`/disputes/{dispute_id}/documents`	Uploads a document to attach as evidence
`GET`	`/disputes/{dispute_id}/documents`	Lists all documents attached to a dispute
`GET`	`/disputes/{dispute_id}/documents/{document_id}`	Downloads a specific document (PDF)
`DELETE`	`/disputes/{dispute_id}/documents/{document_id}`	Deletes a document that has not yet been submitted

Environments

Three environments are available. Use Sandbox for initial integration and testing, UAT for pre-production validation, and Production for live merchant operations.

Environment	Base URL	Auth URL
Sandbox	`https://api-sbx.pre.globalgetnet.com/chb/global-disputes/v1`	`https://api-sbx.pre.globalgetnet.com`
UAT	`https://api.pre.globalgetnet.com/chb/global-disputes/v1`	`https://api.pre.globalgetnet.com/authentication/oauth2/access_token`
Production	`https://api.globalgetnet.com/chb/global-disputes/v1`	`https://api.globalgetnet.com/authentication/oauth2/access_token`

All environments use OAuth 2.0 Client Credentials (client_id / client_secret). Tokens are short-lived (1 hour) and must be renewed via the token endpoint before each session.

4.1 Access to Credentials

Credentials are issued per environment. The method for obtaining them depends on which environment you are targeting.

Sandbox

Sandbox credentials are self-service. Create your account and generate a client_id and client_secret directly at the developer portal:

https://predocs.globalgetnet.com

UAT and Production

To obtain UAT or Production credentials, please contact your Account Manager. Your Account Manager will provide onboarding instructions and coordinate credential generation, including your client_id and client_secret for each environment.

4.2 Prerequisites

To call any endpoint in the Payment Disputes API, you need a valid client_id and client_secret for the target environment (see 4.1 Access to Credentials), and an active OAuth2 access token (see 4.3 Authentication & Authorization).

Sandbox

	Value
Base URL	`https://api-sbx.pre.globalgetnet.com/chb/global-disputes/v1`
Auth URL	`https://api-sbx.pre.globalgetnet.com/authentication/oauth2/access_token`
Credentials	Self-service at predocs.globalgetnet.com

UAT

	Value
Base URL	`https://api.pre.globalgetnet.com/chb/global-disputes/v1`
Auth URL	`https://api.pre.globalgetnet.com/authentication/oauth2/access_token`
Credentials	Provided by Account Manager

Production

	Value
Base URL	`https://api.globalgetnet.com/chb/global-disputes/v1`
Auth URL	`https://api.globalgetnet.com/authentication/oauth2/access_token`
Credentials	Provided by Account Manager

Authentication: OAuth2 Client Credentials (client_id / client_secret)

4.3 Authentication & Authorization

The Chargebacks API uses OAuth 2.0 for authentication and authorization, together with Bearer Tokens for resource access.

bash

curl -X POST https://api.pre.globalgetnet.com/authentication/oauth2/access_token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=client_id" \
  --data-urlencode "client_secret=client_secret"

bash

curl -X POST https://api.pre.globalgetnet.com/authentication/oauth2/access_token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=client_id" \
  --data-urlencode "client_secret=client_secret"

All tokens are short-lived and should be refreshed via the OAuth2 flow. Refresh tokens are supported where applicable.

4.4 Example Authentication Flow

Obtain an access token from /oauth2/access_token
Use the token in all subsequent API calls: Authorization: Bearer <access_token>
Token expires after 1 hour use refresh token if available

Example curl:

bash

curl -X POST https://api.pre.globalgetnet.com/authentication/oauth2/access_token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=client_id" \
  --data-urlencode "client_secret=client_secret"

bash

curl -X POST https://api.pre.globalgetnet.com/authentication/oauth2/access_token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=client_id" \
  --data-urlencode "client_secret=client_secret"

Expected response:

json

{
  "access_token": "Base64...",
  "token_type": "Bearer",
  "expires_in": 3600
}

json

{
  "access_token": "Base64...",
  "token_type": "Bearer",
  "expires_in": 3600
}

4.5 Chargeback Management Process

Contesting a chargeback through the API follows a defined sequence of steps. Each step maps to a dedicated endpoint described in the subsections below.

Step	Action	Section
1	List and filter disputes to identify those requiring action	4.6 List and Filter Disputes
2	Retrieve the full details of a specific dispute	4.7 Chargeback Details
3	Upload evidence documents to support the contestation	4.8 Documents
4	Submit the contestation referencing the uploaded documents	4.8 Documents
5	Monitor the dispute history and track the outcome	4.7 Chargeback Details / 4.10 Retrieve Cycles

For a complete walkthrough with curl examples for each step, see Section 5 End-to-End Example: Contesting a Dispute.

4.6 List and Filter Disputes

Returns a paginated list of disputes assigned to the merchant. Use query parameters to filter by status, date range, or seller.

bash

curl -X GET "https://api.pre.globalgetnet.com/chb/global-disputes/v1/disputes?dispute_status=needs_response&page=0&size=20" \
  --header "Authorization: Bearer {{TOKEN}}"

bash

curl -X GET "https://api.pre.globalgetnet.com/chb/global-disputes/v1/disputes?dispute_status=needs_response&page=0&size=20" \
  --header "Authorization: Bearer {{TOKEN}}"

Tip: filter by dispute_status=needs_response combined with merchant_expiration_date ordering to prioritize disputes requiring immediate action.

Please check all API information via: Portal API Getnet Docs

4.7 Chargeback Details

GET /disputes/{dispute_id}

Retrieves the full details of a specific dispute, including transaction data, card information, merchant details, current status, and all documents attached to the dispute.

Use this endpoint after identifying a dispute in the list (see 4.6) to confirm the dispute_status, check the merchant_expiration_date, and review the reason code before deciding whether to contest or accept.

bash

curl -X GET "https://api.pre.globalgetnet.com/chb/global-disputes/v1/disputes/f4b8b62e-4825-4f98-b6ff-7d7bdf7cdba8" \
  -H "Authorization: Bearer {{TOKEN}}"

bash

curl -X GET "https://api.pre.globalgetnet.com/chb/global-disputes/v1/disputes/f4b8b62e-4825-4f98-b6ff-7d7bdf7cdba8" \
  -H "Authorization: Bearer {{TOKEN}}"

Please check all API information via: Portal API Getnet Docs

4.8 Documents Upload, List, Download, Delete

The Documents API allows the merchant to manage evidence files attached to a dispute. The following operations are available:

Operation	Method	Endpoint
Upload a document	`POST`	`/disputes/{dispute_id}/documents`
List documents	`GET`	`/disputes/{dispute_id}/documents`
Download a document	`GET`	`/disputes/{dispute_id}/documents/{document_id}`
Delete a document	`DELETE`	`/disputes/{dispute_id}/documents/{document_id}`

Important: Upload is only available when dispute_status = needs_response. Documents must be uploaded before submitting a contestation via POST /disputes/{dispute_id}/evidences.

Deletion constraint: A document can only be deleted while dispute_status = needs_response and the document has not yet been submitted as part of a contestation. Once the merchant submits the contestation or accepts the dispute, all uploaded documents are locked and cannot be deleted.

The reason header is required when deleting a document.

File Requirements

Warning: The API validates only file size and format at upload time. Compliance with the specifications below is the merchant's responsibility. Documents that do not meet these requirements may be silently rejected by the card network during dispute processing, causing the contestation to be dismissed without further notice.

Size limits

Constraint	Limit
Maximum size per file	5 MB
Maximum total request size (including headers)	10 MB
Maximum pages per file	18 pages

Multiple files can be attached to a single contestation, provided the total request size does not exceed 10 MB.

Format and resolution

Constraint	Requirement
File format	PDF
Page orientation	Portrait (vertical) recommended
Page size	8.27 × 11.69 inches (A4)
Maximum resolution	300 PPI
Maximum total pixels per page	30,000,000 px

Recommendation: Ensure all pages in a single PDF share the same orientation and dimensions. Mixed-orientation documents may be rejected or misread by the card network.

4.9 Contest a Dispute (Submit Evidence)

POST /disputes/{dispute_id}/evidences

Once all evidence documents have been uploaded (see 4.8 Documents), use this endpoint to formally submit the contestation. Getnet will validate the submission and forward the evidence to the card network for re-evaluation.

This action changes the dispute dispute_status from needs_response to in_review.

Important: This endpoint can only be called when dispute_status = needs_response. All document_id values referenced in the request body must belong to documents already uploaded for this dispute and not yet submitted in a previous contestation.

Request body:

json

{
  "reason": "Customer received the product and signed the delivery receipt.",
  "document_id": [
    "a1c2d3e4-1234-5678-abcd-ef0123456789"
  ]
}

json

{
  "reason": "Customer received the product and signed the delivery receipt.",
  "document_id": [
    "a1c2d3e4-1234-5678-abcd-ef0123456789"
  ]
}

Field	Type	Required	Description
`reason`	string	No	Free-text explanation for the contestation. Visible to Getnet staff during review.
`document_id`	array of strings (UUID)	Yes	IDs of the uploaded documents to be submitted as evidence.

bash

curl -X POST "https://api.pre.globalgetnet.com/chb/global-disputes/v1/disputes/f4b8b62e-4825-4f98-b6ff-7d7bdf7cdba8/evidences" \
  -H "Authorization: Bearer {{TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer received the product and signed the delivery receipt.",
    "document_id": ["a1c2d3e4-1234-5678-abcd-ef0123456789"]
  }'

bash

curl -X POST "https://api.pre.globalgetnet.com/chb/global-disputes/v1/disputes/f4b8b62e-4825-4f98-b6ff-7d7bdf7cdba8/evidences" \
  -H "Authorization: Bearer {{TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer received the product and signed the delivery receipt.",
    "document_id": ["a1c2d3e4-1234-5678-abcd-ef0123456789"]
  }'

A 201 Created response confirms the contestation was received. From this point, the dispute is locked for editing and the merchant should monitor the outcome via 4.10 Retrieve Cycles or 4.7 Chargeback Details.

Please check all API information via: Portal API Getnet Docs

4.10 Retrieve Cycles for a Dispute

GET /disputes/{dispute_id}/cycles

This endpoint allows the merchant to follow the full history of a dispute. Each entry in the response represents a recorded state change a new cycle opened or a status updated and contains a summarized snapshot of the dispute at that point in time.

Each cycle record includes the key information that was current at the moment of the event:

Field	Description
`cycle`	The dispute cycle active at the time of the event (e.g., `first_chargeback`, `second_presentment`)
`dispute_status`	The dispute status at the time of the event (e.g., `needs_response`, `in_review`, `dispute_won`)
`merchant_status`	The merchant-facing status at the time of the event
`amount` / `currency_code`	The disputed amount and currency applicable to that cycle
`merchant_expiration_date`	The deadline specific to the merchant for submitting evidence
`cycle_create_date`	The date the card brand sent the incoming request for that cycle
`backoffice_merchant_response`	Any feedback from Getnet staff, such as reasons for document rejection
`created_at`	Timestamp when this cycle record was created in the system

By calling this endpoint over time, the merchant can reconstruct the complete timeline of a dispute from the first notification through contestation, re-evaluation, and final resolution.

bash

curl -X GET "https://api.pre.globalgetnet.com/chb/global-disputes/v1/disputes/f4b8b62e-4825-4f98-b6ff-7d7bdf7cdba8/cycles" \
  -H "Authorization: Bearer {{TOKEN}}"

bash

curl -X GET "https://api.pre.globalgetnet.com/chb/global-disputes/v1/disputes/f4b8b62e-4825-4f98-b6ff-7d7bdf7cdba8/cycles" \
  -H "Authorization: Bearer {{TOKEN}}"

Example response:

json

[
  {
    "cycle": "first_chargeback",
    "dispute_status": "needs_response",
    "merchant_status": "merchant_notified",
    "amount": 20000,
    "currency_code": "MXN",
    "merchant_expiration_date": "2024-02-24T23:59:59.000Z",
    "cycle_create_date": "2024-02-09T13:02:43.762Z",
    "dispute_reason_code": "4853",
    "dispute_reason_name": "Cardholder Dispute",
    "backoffice_merchant_response": null,
    "created_at": "2024-02-09T13:05:00.441Z"
  },
  {
    "cycle": "second_presentment",
    "dispute_status": "in_review",
    "merchant_status": "verification_required",
    "amount": 20000,
    "currency_code": "MXN",
    "merchant_expiration_date": null,
    "cycle_create_date": null,
    "dispute_reason_code": "4853",
    "dispute_reason_name": "Cardholder Dispute",
    "backoffice_merchant_response": null,
    "created_at": "2024-02-25T09:14:22.123Z"
  }
]

json

[
  {
    "cycle": "first_chargeback",
    "dispute_status": "needs_response",
    "merchant_status": "merchant_notified",
    "amount": 20000,
    "currency_code": "MXN",
    "merchant_expiration_date": "2024-02-24T23:59:59.000Z",
    "cycle_create_date": "2024-02-09T13:02:43.762Z",
    "dispute_reason_code": "4853",
    "dispute_reason_name": "Cardholder Dispute",
    "backoffice_merchant_response": null,
    "created_at": "2024-02-09T13:05:00.441Z"
  },
  {
    "cycle": "second_presentment",
    "dispute_status": "in_review",
    "merchant_status": "verification_required",
    "amount": 20000,
    "currency_code": "MXN",
    "merchant_expiration_date": null,
    "cycle_create_date": null,
    "dispute_reason_code": "4853",
    "dispute_reason_name": "Cardholder Dispute",
    "backoffice_merchant_response": null,
    "created_at": "2024-02-25T09:14:22.123Z"
  }
]

Please check all API information via: Portal API Getnet Docs

4.11 Security and 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

5. End-to-End Example: Contesting a Dispute

The following walkthrough shows the complete sequence for identifying a dispute that requires a response, inspecting its details, uploading evidence, and submitting a contestation.

Step 1 List disputes with pending action

Filter disputes by dispute_status=needs_response to find those awaiting merchant action. See 4.6 List and Filter Disputes for all available filters.

bash

curl -X GET "https://api.pre.globalgetnet.com/chb/global-disputes/v1/disputes?dispute_status=needs_response&limit=10&page=1" \
  -H "Authorization: Bearer {{TOKEN}}"

bash

curl -X GET "https://api.pre.globalgetnet.com/chb/global-disputes/v1/disputes?dispute_status=needs_response&limit=10&page=1" \
  -H "Authorization: Bearer {{TOKEN}}"

From the response, note the dispute_id of the dispute you want to contest:

json

[
  {
    "dispute": {
      "dispute_id": "f4b8b62e-4825-4f98-b6ff-7d7bdf7cdba8",
      "merchant_name": "My Store",
      "amount": "20000",
      "currency": "484",
      "situation": {
        "dispute_status": "needs_response",
        "merchant_status": "merchant_notified",
        "cycle": "first_chargeback",
        "dispute_reason_code": "4853",
        "dispute_reason_name": "Cardholder Dispute",
        "merchant_expiration_date": "2024-02-24T23:59:59.000Z"
      }
    }
  }
]

json

[
  {
    "dispute": {
      "dispute_id": "f4b8b62e-4825-4f98-b6ff-7d7bdf7cdba8",
      "merchant_name": "My Store",
      "amount": "20000",
      "currency": "484",
      "situation": {
        "dispute_status": "needs_response",
        "merchant_status": "merchant_notified",
        "cycle": "first_chargeback",
        "dispute_reason_code": "4853",
        "dispute_reason_name": "Cardholder Dispute",
        "merchant_expiration_date": "2024-02-24T23:59:59.000Z"
      }
    }
  }
]

Step 2 Retrieve dispute details

Use the dispute_id to fetch the full details of the dispute, including transaction data and current status. See 4.7 Chargeback Details.

bash

curl -X GET "https://api.pre.globalgetnet.com/chb/global-disputes/v1/disputes/f4b8b62e-4825-4f98-b6ff-7d7bdf7cdba8" \
  -H "Authorization: Bearer {{TOKEN}}"

bash

curl -X GET "https://api.pre.globalgetnet.com/chb/global-disputes/v1/disputes/f4b8b62e-4825-4f98-b6ff-7d7bdf7cdba8" \
  -H "Authorization: Bearer {{TOKEN}}"

Confirm the dispute_status is needs_response and note the merchant_expiration_date this is your deadline to submit evidence.

Step 3 Upload evidence document

Upload a PDF file with the supporting evidence (e.g., proof of delivery, invoice, communication records). See 4.8 Documents for file requirements.

bash

curl -X POST "https://api.pre.globalgetnet.com/chb/global-disputes/v1/disputes/f4b8b62e-4825-4f98-b6ff-7d7bdf7cdba8/documents" \
  -H "Authorization: Bearer {{TOKEN}}" \
  -F "description=Proof of delivery signed by customer" \
  -F "file=@proof_of_delivery.pdf"

bash

curl -X POST "https://api.pre.globalgetnet.com/chb/global-disputes/v1/disputes/f4b8b62e-4825-4f98-b6ff-7d7bdf7cdba8/documents" \
  -H "Authorization: Bearer {{TOKEN}}" \
  -F "description=Proof of delivery signed by customer" \
  -F "file=@proof_of_delivery.pdf"

A 201 Created response confirms the upload was successful. Note the document_id returned you will need it in the next step.

json

{
  "document_id": "a1c2d3e4-1234-5678-abcd-ef0123456789"
}

json

{
  "document_id": "a1c2d3e4-1234-5678-abcd-ef0123456789"
}

You can upload multiple documents before submitting. Each must be uploaded individually.

Step 4 Submit the contestation

Once all documents are uploaded, submit the contestation by referencing the document_id(s). This triggers Getnet to forward the evidence to the card network for re-evaluation.

bash

curl -X POST "https://api.pre.globalgetnet.com/chb/global-disputes/v1/disputes/f4b8b62e-4825-4f98-b6ff-7d7bdf7cdba8/evidences" \
  -H "Authorization: Bearer {{TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer received the product and signed the delivery receipt.",
    "document_id": ["a1c2d3e4-1234-5678-abcd-ef0123456789"]
  }'

bash

curl -X POST "https://api.pre.globalgetnet.com/chb/global-disputes/v1/disputes/f4b8b62e-4825-4f98-b6ff-7d7bdf7cdba8/evidences" \
  -H "Authorization: Bearer {{TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer received the product and signed the delivery receipt.",
    "document_id": ["a1c2d3e4-1234-5678-abcd-ef0123456789"]
  }'

A 201 Created response confirms the contestation was received. The dispute dispute_status will transition to in_review.

Step 5 Monitor the outcome

Poll the dispute cycles to track the resolution. See 4.10 Retrieve Cycles.

bash

curl -X GET "https://api.pre.globalgetnet.com/chb/global-disputes/v1/disputes/f4b8b62e-4825-4f98-b6ff-7d7bdf7cdba8/cycles" \
  -H "Authorization: Bearer {{TOKEN}}"

bash

curl -X GET "https://api.pre.globalgetnet.com/chb/global-disputes/v1/disputes/f4b8b62e-4825-4f98-b6ff-7d7bdf7cdba8/cycles" \
  -H "Authorization: Bearer {{TOKEN}}"

When the dispute reaches a final status (dispute_won, dispute_lost, or dispute_partially_won), the cycle history will reflect the full timeline of the resolution.

6. Webhooks Real-Time Chargeback Notifications

The Getnet Webhook system allows merchants to receive near real-time notifications when a new chargeback arrives on the platform, eliminating the need to poll the disputes list endpoint periodically.

When a new chargeback is assigned to your merchant account and requires a response, Getnet sends an HTTP POST request with a JSON payload to the callback URL registered in your subscription.

For the complete Webhooks reference including subscription management, authentication methods, retry logic, and all available event types see the official documentation:

Webhooks Reference predocs.globalgetnet.com

6.1 Chargeback events

Currently, there is one chargeback event available for webhook subscription:

Event	Trigger
`CHARGEBACK_NEEDS_RESPONSE`	A new chargeback has been assigned to the merchant and requires a response

The CHARGEBACK_NEEDS_RESPONSE event is fired when a new chargeback is registered on the platform and the merchant must take action. The notification payload is an array of dispute objects. When more than 100 disputes are pending notification, they are delivered in batches of up to 100 items per request.

Upon receiving this event, the recommended flow is:

Extract the dispute_id from each item in the array.
Call 4.7 Chargeback Details to retrieve the full dispute data.
Upload supporting evidence via 4.8 Documents.
Submit the contestation via POST /disputes/{dispute_id}/evidences.

Example payload:

json

[
  {
    "idempotency_key": "a3f9c12e-8b47-4d02-bc1e-9f2d3a4e5b67",
    "dispute_id": "f4b8b62e-4825-4f98-b6ff-7d7bdf7cdba8",
    "affiliation_code": "674179",
    "event_type": "CHARGEBACK_NEEDS_RESPONSE",
    "cycle": "first_chargeback",
    "dispute_status": "needs_response",
    "merchant_status": "merchant_notified",
    "merchant_expiration_date": "2024-02-24T23:59:59.000Z",
    "reason_code": "4853",
    "amount": 20000,
    "currency": "MXN",
    "transaction_date": "2024-01-15T10:22:00.000Z",
    "acquirer_reference_number": "40397095747133411680659"
  }
]

json

[
  {
    "idempotency_key": "a3f9c12e-8b47-4d02-bc1e-9f2d3a4e5b67",
    "dispute_id": "f4b8b62e-4825-4f98-b6ff-7d7bdf7cdba8",
    "affiliation_code": "674179",
    "event_type": "CHARGEBACK_NEEDS_RESPONSE",
    "cycle": "first_chargeback",
    "dispute_status": "needs_response",
    "merchant_status": "merchant_notified",
    "merchant_expiration_date": "2024-02-24T23:59:59.000Z",
    "reason_code": "4853",
    "amount": 20000,
    "currency": "MXN",
    "transaction_date": "2024-01-15T10:22:00.000Z",
    "acquirer_reference_number": "40397095747133411680659"
  }
]

Payload field descriptions:

Field	Type	Description
`idempotency_key`	string (UUID)	Unique key per delivery — use to deduplicate events processed more than once
`dispute_id`	string (UUID)	The dispute identifier — use in all subsequent API calls
`affiliation_code`	string	Merchant affiliation code used by the card brand
`event_type`	string	Always `CHARGEBACK_NEEDS_RESPONSE` for this event
`cycle`	string	The active dispute cycle (e.g., `first_chargeback`, `retrieval_request`)
`dispute_status`	string	Always `needs_response` at notification time
`merchant_status`	string	Always `merchant_notified` at notification time
`merchant_expiration_date`	string (ISO 8601)	Deadline by which the merchant must respond
`reason_code`	string	Reason code assigned by the card brand (see Section 7)
`amount`	number	Disputed amount in the smallest currency unit (e.g., cents)
`currency`	string	ISO 4217 alpha-3 currency code (e.g., `MXN`, `BRL`, `CLP`)
`transaction_date`	string (ISO 8601)	Date and time of the original disputed transaction
`acquirer_reference_number`	string	Acquirer reference number (ARN) for the transaction

Batching: If more than 100 disputes are queued for notification, Getnet delivers them in multiple requests, each containing up to 100 items in the array.

6.2 Endpoint Requirements

Your webhook endpoint must:

Accept HTTP POST requests
Use HTTPS with a valid SSL certificate
Respond with HTTP 204 (No Content) to acknowledge successful receipt
Be idempotent the same event may be delivered more than once (use idempotency_key to deduplicate)

If your endpoint returns any status code other than 204, Getnet considers the delivery failed and will retry the webhook.

6.3 Subscription Setup

Webhook subscriptions are managed via the Webhook Management API. To subscribe to chargeback events:

bash

curl -X POST " https://api.pre.globalgetnet.com/webhooks/v1/subscriptions" \
  -H "Authorization: Bearer {{TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "CHARGEBACK_NEEDS_RESPONSE",
    "callback_url": "https://your-system.example.com/webhooks/chargeback",
    "authentication_type": "oauth",
    "authentication_data": {
      "oauth_url": "https://your-auth-server.example.com/token",
      "client_id": "your_client_id",
      "client_secret": "your_client_secret"
    }
  }'

bash

curl -X POST " https://api.pre.globalgetnet.com/webhooks/v1/subscriptions" \
  -H "Authorization: Bearer {{TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "CHARGEBACK_NEEDS_RESPONSE",
    "callback_url": "https://your-system.example.com/webhooks/chargeback",
    "authentication_type": "oauth",
    "authentication_data": {
      "oauth_url": "https://your-auth-server.example.com/token",
      "client_id": "your_client_id",
      "client_secret": "your_client_secret"
    }
  }'

For all available authentication methods (Basic Auth, OAuth 2.0, Bearer Token) and subscription management endpoints, refer to the Webhooks Reference.

7. Chargeback Reason Codes

Reason codes are standardized numeric or alphanumeric identifiers assigned by card networks (Visa, Mastercard, American Express, Discover) to explain why a transaction is being disputed. Each code corresponds to a specific category such as fraud, authorization issues, processing errors, or consumer disputes.

Endpoint: GET /reason-codes

bash

curl -X GET "https://api.pre.globalgetnet.com/chb/global-disputes/v1/reason-codes" \
  -H "Authorization: Bearer {{TOKEN}}"

bash

curl -X GET "https://api.pre.globalgetnet.com/chb/global-disputes/v1/reason-codes" \
  -H "Authorization: Bearer {{TOKEN}}"

PROSA (Domestic Mexico only)

Code	Description	Category
41	Periodic charge cancelled or NOT requested / Mass transport	Services
57	Multiple transaction not requested by the merchant	Fraud
60	Original or copy received illegible, with incomplete or incorrect data	Processing
63	Chip (EMV)	Fraud
64	Manual transaction at electronic terminal	Fraud
68	Fraudulent telephone/mail/Internet order transaction	Fraud
70	Card reported lost or stolen	Fraud
71	Authorization declined	Authorization
72	Transaction exceeds authorized amount or lack of authorization	Authorization
74	Late submission	Authorization
75	Authorization does not exist	Authorization
76	Road toll / TAG	Services
79	Copy or original of requested promissory note not received	Processing
80	Processing error	Processing
82	Duplicate process	Processing
84	Missing signature and/or signature on file	Processing
85	Return not processed	Processing
86	Amount alteration	Fraud
92	Payment recipient with irregular activity	Processing
94	Cancellation of guaranteed reservation, delayed charges and/or payment by other means	Services

Discover

Code	Description	Category
4755	Non-Receipt of Goods or Services	Services
4752	Does Not Recognize	Fraud
4586	Altered Amount	Fraud
4865	Paid By Other Means	Fraud
4534	Duplicate Processing	Processing
4867	Fraud Chip Card and PIN Transaction	Fraud
4863	Authorization Non Compliance	Fraud
8002	Credit Not Processed	Processing
7030	Fraud Card Not Present Transaction	Fraud
4550	Credit/Debit Posted Incorrectly	Fraud

American Express (Amex)

Code	Description	Category
4507	Incorrect Transaction Amount or Card Number Does Not Match	Fraud
4512	Multiple Processing	Fraud
4513	Credit Not Presented	Fraud
4515	Paid by Other Means	Fraud
4516	Investigation Without Response	Fraud
4517	Insufficient Response	Fraud
4521	Authorization	Fraud
4530	Currency Error	Fraud
4534	Multiple Charges	Processing
4536	Late Submission	Fraud
4540	Card Not Present	Fraud
4553	Goods/Services Inconsistent with Description, Damaged or Defective	Services
4554	Goods/Services Not Received or Only Partially Received	Fraud
4750	Vehicle Rental: Major Damage, Theft or Loss of Use	Fraud
4527	Coupon without Card Imprint	Processing
4544	Recurring Billing Cancelled	Processing
4798	Counterfeit Card	Processing

Visa

Reason Code	Category
10.1: EMV Liability Shift Counterfeit Fraud	Fraud
10.2: EMV Liability Shift – Non-Counterfeit Fraud	Fraud
10.3: Other Fraud – Card-Present Environment	Fraud
10.4: Other Fraud – Card-Absent Environment	Fraud
10.5: Visa Fraud Monitoring Program – Invalid Disputes	Fraud
11.1: Card Recovery Bulletin	Authorization
11.2: Declined Authorization	Authorization
11.3: No Authorization / Late Presentment	Authorization
12.2: Incorrect Transaction Code	Processing Errors
12.3: Incorrect Currency	Processing Errors
12.4: Incorrect Account Number	Processing Errors
12.5: Incorrect Amount	Processing Errors
12.6: Duplicate Processing / Paid by Other Means	Processing Errors
12.7: Invalid Data	Processing Errors
13.1: Merchandise/Services Not Received	Consumer Disputes
13.2: Cancelled Recurring Transaction	Consumer Disputes
13.3: Not as Described or Defective Merchandise/Services	Consumer Disputes
13.4: Counterfeit Merchandise	Consumer Disputes
13.5: Misrepresentation	Consumer Disputes
13.6: Credit Not Processed	Consumer Disputes
13.7: Cancelled Merchandise/Services	Consumer Disputes
13.8: Original Credit Transaction Not Accepted	Consumer Disputes
13.9: Non-Receipt of Cash at an ATM	Consumer Disputes

Mastercard

Reason Code	Category
4807: Warning Bulletin File	Authorization
4808: Authorization-Related Chargeback	Authorization
4812: Account Number Not On File	Authorization
4834: Point-of-Interaction Error	Point-of-Interaction Error
4831: Transaction Amount Differs	Point-of-Interaction Error
4842: Late Presentment	Point-of-Interaction Error
4846: Correct Transaction Currency Code Not Provided	Point-of-Interaction Error
4850: Installment Billing Dispute	Point-of-Interaction Error
4837: No Cardholder Authorization	Fraud
4840: Fraudulent Processing of Transactions	Fraud
4849: Questionable Merchant Activity	Fraud
4863: Cardholder Does Not Recognize Potential Fraud	Fraud
4870: Chip Liability Shift	Fraud
4871: Chip/PIN Liability Shift	Fraud
4853: Cardholder Dispute	Cardholder Disputes
4841: Canceled Recurring or Digital Goods Transactions	Cardholder Disputes
4855: Goods or Services Not Provided	Cardholder Disputes
4859: Addendum, No-show, or ATM Dispute	Cardholder Disputes
4860: Credit Not Processed	Cardholder Disputes

8. Best Practices

Send legible documents (PDF / JPEG / PNG) and provide clear descriptions.
Use filters in the list to prioritize disputes with dispute_status = needs_response and deadline (merchant_expiration_date).
Save dispute_id and document_id for future calls.
In production, store client_id / client_secret securely avoid versioning credentials.

9. Frequently Asked Questions (FAQs)

Is the chargeback API a secure product? Yes, it has been tested by EHT and is authenticated.

Who bears the financial loss of the chargeback? In most cases, the loss falls on the retailer, who has the sale amount reversed from their account, even if the product has already been shipped.

What is the deadline for a customer to request a chargeback? The standard time limit varies, but generally the customer has 45 to 180 days to dispute a purchase.

Is the merchant always liable in cases of fraud? No. The merchant may be held liable if they do not take the necessary precautions to verify the transaction and the buyer's identity (e.g., anti-fraud systems).

How does Getnet notify me about a chargeback? Getnet sends real-time webhook notifications to your registered callback URL when a new chargeback requires your attention. Email notifications via the Merchant Portal are also available. See Section 6 — Webhooks for setup details.

What documents do I need to send to dispute a chargeback? The necessary documentation varies depending on the reason (fraud, commercial disagreement, etc.) and may include invoices, proof of delivery (tracking), emails exchanged with the customer, and an explanatory letter. Access the Merchant Portal to consult the PDF guidance by country, or use the reason-code endpoint for guidelines on what to send.

What document formats and sizes can businesses send through the API? Documents must be in PDF format. Each document can be a maximum of 5 MB.

Does Getnet help me with the dispute? Yes. Acquirers provide the interface for sending the necessary documentation, which is then forwarded to the card-issuing bank for analysis. The platform provides guidance on the process.

Are there extra costs or penalties for a high volume of chargebacks? Yes. An excessive number of chargebacks can lead to penalties by card brands (Visa/Mastercard) and, in extreme cases, to the suspension of the shop's payment services.

What is "friendly fraud" and how does the platform help me prove the purchase was legitimate? Friendly fraud occurs when the customer makes a purchase but then disputes it. The platform assists in collecting and sending evidence such as communication records and confirmation of receipt to refute the dispute.

On this page

Chargeback Management