Global Payments API
GP Developer PortalGP API reference
HomeAPI ReferenceSDKsContext Plugin
Disputes

List Disputes

GET
/disputes

Get a list of disputes recently processed, using criteria passed in the query string. Page through the result set to access all records. Availability of this feature in production depends on your allowed live configuration. Please contact Global Payments before coding this feature to confirm it will be available to you when you go live.

Authorization

bearerAuth
AuthorizationBearer <token>

Access token from POST /accesstoken, sent as Authorization: Bearer <token>.

In: header

Query Parameters

page?number

Indicates the page sequence to return in the response. The number of records presented on each page is determined by page_size field.1 means the first page, 2 the second and so on.

Default1
page_size?number

The total number of records to return in a single page for a list. The maximum this value can be is 1000, meaning that the maximum number of records to return in a single request is 1000.

Range1 <= value <= 1000
Default5
order?string

The direction of the ordering of the entire list, ASC or DESC

Value in

  • "ASC"
  • "DESC"
order_by?string

The field to order the list by.

Default"TIME_CREATED"
arn?string

ARN ot Acquirer Reference Number is a Global Payments created reference sent to the card brands to identify transactions.

Length1 <= length <= 50
brand?string

Indicates the card brand that issued the card.

Value in

  • "VISA"
  • "MASTERCARD"
  • "AMEX"
  • "DINERS"
  • "DISCOVER"
  • "JCB"
  • "CUP"
status?string

Indicated where the dispute is in the life-cycle.

Length1 <= length <= 50

Value in

  • "UNDER_REVIEW"
  • "WITH_MERCHANT"
  • "CLOSED"
  • "FUNDED"
stage?string

This field indicates the distinct step a dispute is at, within the dispute lifecycle.

  • RETRIEVAL - Request for proof that a transaction was valid. Merchant must supply documentation within a specific timeframe. No financial adjustments are performed however, if the timeframe expires before there is a response, the merchant can be held liable.
  • CHARGEBACK - The cardholder or issuing bank disputes a transaction and funds are returned to the issuer/cardholder. The merchant can accept or challenge the dispute by supplying documentation proving the transaction was valid.
  • REVERSAL - The issuer decides the chargeback submitted is invalid. If funds were taken from the merchant, those funds are returned.
  • SECOND_CHARGEBACK - This is a subsequent escalation of a chargeback wherein the issuer/cardholder continues to dispute the transaction after the merchant has responded to defend the case.
  • PRE_ARBITRATION - This is a further subsequent escalation of a chargeback wherein the issuer/cardholder continues to dispute the transaction after the merchant has responded to defend the case.
  • ARBITRATION - This is the final escalation stage where the card brand is asked to rule on the dispute.
  • PRE_COMPLIANCE - An initial compliance violation of the card processing rules that are defined by the relevant card association.
  • COMPLIANCE - This is the final compliance escalation stage created wherein the card brand is asked to rule on the dispute.
  • GOODFAITH - This is a request to accept liability for a case on a good faith basis, even though the final deadline for resolving the case has passed.
  • MASTERCARD PRE-DISPUTE - This is an initial stage for Mastercard holders where Disputes are attempted to be resolved initially between the acquirer and the Merchant before a chargeback occurs
Length1 <= length <= 50

Value in

  • "RETRIEVAL"
  • "CHARGEBACK"
  • "REVERSAL"
  • "SECOND_CHARGEBACK"
  • "PRE_ARBITRATION"
  • "ARBITRATION"
  • "PRE_COMPLIANCE"
  • "COMPLIANCE"
  • "GOODFAITH"
  • "MASTERCARD PRE-DISPUTE"
from_stage_time_created?from_stage_time_created

The start time to search for in a range, using stage_time_created value. Note that if this is not specified, it will be defaulted to one month prior to the current date

Formatdate
to_stage_time_created?to_stage_time_created

The end time to search for in a range, using stage_time_created value

Formatdate
system.mid?string

The system merchant identifier.

Length1 <= length <= 50
system.hierarchy?string

Identifies the location of a merchant within the merchant's corporate hierarchical structure. The structure for each gateway can be seen below: GPN - > ---- HPY --> EVO --> --

Length1 <= length <= 50
deposit_id?string

A unique identifier for the object created by Global Payments. The first 3 characters identifies the resource an id relates to.

order.reference?string

Merchant defined field to reference the order

acquirer_code?string

Contains the acquirer code which helps identify the processing gateway.

  • GPN - Global gateway
  • HPY - Heartland gateway.
  • EVO - EVO gateway

Value in

  • "GPN"
  • "HPY"
  • "EVO"

Header Parameters

X-GP-Version*string

The version of the API to execute the request.

Length1 <= length <= 50
Default"2021-03-22"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/disputes" \  -H "X-GP-Version: 2021-03-22"
{  "total_record_count": 1000,  "current_page_size": 564,  "merchant_id": "MER_c4c0df11039c48a9b63701adeaa296c3",  "merchant_name": "Sandbox_merchant_2",  "account_id": "TRA_86920f927028745yt34d077d88beb29b",  "account_name": "transaction_processing",  "filter": {    "page": 1,    "page_size": 5,    "order": "ASC",    "order_by": "TIME_CREATED",    "arn": "string",    "brand": "VISA",    "status": "UNDER_REVIEW",    "stage": "RETRIEVAL",    "from_stage_time_created": "2019-08-24",    "to_stage_time_created": "2019-08-24",    "system.mid": "string",    "system.hierarchy": "string"  },  "paging": {    "page": 1,    "page_size": 5,    "order_by": "TIME_CREATED",    "order": "ASC"  },  "disputes": [    {      "id": "DIS_SAND_abcd1236",      "status": "UNDER_REVIEW",      "stage": "RETRIEVAL",      "stage_time_created": "2021-02-22T10:24:43.999Z",      "amount": "11099",      "currency": "USD",      "reason_code": "FRAUD",      "reason_description": "string",      "time_to_respond_by": "2025-02-22T10:24:43.761Z",      "result": "PENDING",      "acquirer_code": "GPN",      "system": {        "mid": "string",        "tid": "string",        "hierarchy": "string",        "name": "MERCHANT ABC INC",        "dba": "MERCHANT XYZ INC"      },      "last_adjustment_amount": "1999",      "last_adjustment_currency": "USD",      "last_adjustment_funding": "DEBIT",      "transaction": {        "order": {          "reference": "b636294sd5b6826hjdnde92"        }      },      "payment_method": {        "card": {          "number": "string",          "arn": "string",          "brand": "VISA"        }      }    }  ],  "action": {    "id": "ACT_uzFr7t4VOqxdLDI44hHmXIjHtOOE8d",    "type": "DISPUTE_SINGLE",    "time_created": "2021-05-03T21:23:39.718Z",    "result_code": "SUCCESS",    "app_id": "uzFr7t4VOqxdLDI44hHmXIjHtOOE8d",    "app_name": "my_lovely_app"  }}

Close a Batch POST

Close a Batch without using the Global Payments Batch id Closing a batch results in commencement of funding to the merchant all the transactions in that batch. Here you can close the current open batch without the unique batch id. Availability of this feature in production depends on your allowed live configuration. Please contact Global Payments before coding this feature to confirm it will be available to you when you go live.

Get a Dispute GET

Get info about a Dispute on the Global Payments system using the unique id created by Global Payments for that Dispute. Availability of this feature in production depends on your allowed live configuration. Please contact Global Payments before coding this feature to confirm it will be available to you when you go live.