For AI agents: the complete documentation index is at /llms.txt, and the full text of every page is at /llms-full.txt. Most pages are also available as Markdown by adding .md to the URL.

Manage Disputes

Learn how to automate the reporting and handling of disputes

As an embedded payments partner, you can use our API to handle disputes automatically. In this guide, you’ll learn how to retrieve dispute cases, view details, and either accept or challenge disputes.

Prerequisites

Before starting the steps in this guide, make sure you:

Get set up in our Sandbox test environment:
- Get registered
- Get Partner-level Sandbox test credentials (contact our support team)
- Create an access token
Have at least one boarded merchant under your partnership

Step 1: Receive dispute webhook

When a dispute is raised against a transaction, you will be notified via a webhook. This notification includes key details such as the Transaction ID (TRN_ID) and dispute status, which allows you to take the appropriate next steps.

Sample webhook payload

{
    "merchant_id": "MER_2fe98adf1b084ea98b2bea6c13822718",
    "id": "TRN_VsycrvUsGjauHNY3sPWkK6x4zbDprr",
    "disputes": {
        "amount": "$670.74",
        "fee_amount_decimal": "$0.00",
        "status": "WITH_MERCHANT",
        "reason_description": "Cardholder Does Not Recognize - Potential Fraud"
    },
    "action": {
        "id": "ACT_12HNTJbo2t3pKTitzhCHjjNs2QqfZ7",
        "type": "DISPUTE_INITIATED_STATUS_NOTIFICATION",
        "time_created": "2024-05-16T16:00:37.778Z",
        "result_code": "SUCCESS",
        "app_id": "Q5hHBBzb54MnRT4aNbOnezZO9Afzl27q",
        "app_name": "Sample_App"
    }
}

Step 2: Retrieve a list of disputes (optional)

Alternatively, you can retrieve a list of disputes for a specified date range. You can optionally filter by card brand, dispute stage, status (for example, New, Under Review, Closed), pagination details, and more.

As a partner, you have the ability to get a list of disputes raised against one of your merchants. The data only goes back two years, and the date range must be within 31 days. A 30-minute waiting time is required for any report where the same date range and merchant applies.

Sample request

curl --location --request GET 'https://apis.sandbox.globalpay.com/ucp/merchants/MER_2fe98adf1b084ea98b2bea6c13822718/accounts/FMA_9767c398bdd345c0a1b7f3edbb419ac4/disputes' \
--header 'X-GP-Version: 2021-03-22' \
--header 'Authorization: Bearer eM1BIwT2CAr1MpC2VlwMvhNXvmy4' \
--header 'Content-Type: application/json

Sample response

{
  "total_record_count": 1,
  "current_page_size": 1,
  "merchant_id": "{MER_id}",
  "merchant_name": "merchant name",
  "account_id": "{FMA_id}",
  "account_name": "account name",
  "filter": {
      "from_time_created": "2023-02-18T00:00:00.000Z",
      "to_time_created": "2023-03-20T23:59:59.999Z"
  },
  "paging": {
      "page_size": 2,
      "page": 1
  },
  "disputes": [
      {
          "id": "{DIS_id}",
          "status": "WITH_MERCHANT",
          "stage": "CHARGEBACK",
          "stage_time_created": "2021-03-03T15:41:33",
          "amount": "200",
          "currency": "USD",
          "reason_code": "",
          "reason_description": "No Valid Authorization",
          "transaction": {
              "id": "TRN_CElICyHklysk1hth3JsEqMlQPRPrjm",
              "time_created": "2021-02-08T15:41:33",
              "type": "SALE",
              "amount": "200",
              "currency": "USD",
              "reference": "2801207a017M"
          },
          "link": {
              "rel": "challenge",
              "href": "https://apis.sandbox.globalpay.com/ucp/merchants/MER_f582a258fdc947e4983d4eb682de18c8/transactions/TRN_CElICyHklysk1hth3JsEqMlQPRPrjm/challenge"
          }
      }
  ],
  "action": {
      "id": "ACT_Xo6RjwmmPwO12wA1cRUr5hqV1SnA2k",
      "type": "DISPUTE_LIST",
      "time_created": "2021-03-10T15:41:33.961Z",
      "result_code": "SUCCESS",
      "app_id": "i9R0byBBor6RqTQNj3g4MuVBwH5rd7yR",
      "app_name": "demo_app"
  }
}

Step 3: Challenge a dispute (optional)

If a merchant wants to challenge a dispute, they can provide documentation proving the transaction is valid.

Sample request

curl --location –request POST ‘https://apis.sandbox.globalpay.com/ucp/merchants/MER_2fe98adf1b084ea98b2bea6c13822718/transactions/TRN_VsycrvUsGjauHNY3sPWkK6x4zbDprr/challenge’ \
--header 'X-GP-Version: 2021-03-22' \
--header 'Authorization: Bearer A4hPJEYQnARjtNLnsHgOkz2e6yzU' \
--header 'Content-Type: application/json' \
\
--data-raw '{
"documents":{
    "b64_content":"65196581=",
    "file_format":"DOC"}}
Sample response
JSON
{
  "id": "TRN_VsycrvUsGjauHNY3sPWkK6x4zbDprr",
  "dispute_status": "UNDER_REVIEW",
  "status": "SUCCESS",
  "document_name": "DISPUTE_CHALLENGE_718578627_3",
  "action": {
      "id": "ACT_qJWBdlyXNrlZN5IkIAhZbzGnd8qgvW",
      "type": "DOCUMENT_UPLOAD",
      "time_created": "2021-12-21T17:23:42.019Z",
      "result_code": "SUCCESS",
      "app_id": "U1lRHKomEn7DN907RCDPxVhyMfiMLcfy",
      "app_name": "demo_app"
  }
}

Integration references

To get a deeper understanding of risk management, we recommend that you use our provided integration references for both API and SDK integrations. For the full detailed API specification, see the API Explorer.

/transactions - API Explorer

See the full API specification for transaction actions.

/disputes - API Explorer

See the full API specification for dispute actions.

SDKs & Libraries

Add server-side or client-side code to your integration.

Testing

This solution is available for testing in our free Sandbox environment for registered users of this developer portal. Use our resources below to start testing different scenarios.

Test Cards

Test different transaction outcomes with simulated cards or banks.

Postman Collection

View, import, or fork our API collection in Postman.

Responses

View successful responses, HTTP status codes, action response data, and errors.

Next steps

Below are recommended next steps for your partner integration.

Money Movement

Control the entire fund flow lifecycle for your merchants.

Merchant Management & Reporting

Use account data to better support your merchants.

Request a Limit Increase

Submit documentation to increase processing limits.