Disputes

Handle disputes (chargebacks and retrievals).

Retrieve a list of disputes

Retrieve a list of disputes.

Request
Security:
query Parameters
filter
string

The collection items filter requires a special format. Use "," for multiple allowed values. Use ";" for multiple fields. See the filter guide for more options and examples about this format.

sort
Array of strings

The collection items sort field and order (prefix with "-" for descending sort).

limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

q
string

The partial search of the text fields.

expand
string

Expand a response to get a full related object included inside of the _embedded path in the response. It accepts a comma-separated list of objects to expand. See the expand guide for more info.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Deprecated

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200

A list of disputes was retrieved successfully.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

get/disputes
Request samples
$disputes = $client->disputes()->search([
    'filter' => 'transactionId:testId',
]);
Response samples
application/json
[
  • {
    }
]

Create a dispute

Create a dispute.

Request
Security:
header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Deprecated

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json

Dispute resource.

transactionId
required
string

The dispute's transaction ID.

currency
required
string 3 characters

ISO 4217 alphabetic currency code.

amount
required
number <double>

The dispute amount.

acquirerReferenceNumber
string

The dispute's acquirer reference number.

caseId
string

The case ID for the dispute.

reasonCode
required
string

The dispute's reason code.

Enum: "1000" "10.1" "10.2" "10.3" "10.4" "10.5" "11.1" "11.2" "11.3" "12" … 156 more
type
required
string

The dispute's type.

Enum: "information-request" "first-chargeback" "second-chargeback" "arbitration" "fraud" "ethoca-alert" "verifi-alert"
status
required
string

The dispute's status.

Enum: "response-needed" "under-review" "forfeited" "won" "lost" "unknown"
postedTime
required
string <date-time>

Dispute posted time.

deadlineTime
string <date-time>

Dispute deadline time.

Responses
201

Dispute was created.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

422

Invalid data was sent.

post/disputes
Request samples
application/json
{
  • "transactionId": "string",
  • "currency": "USD",
  • "amount": 0,
  • "acquirerReferenceNumber": "string",
  • "caseId": "string",
  • "reasonCode": "1000",
  • "type": "information-request",
  • "status": "response-needed",
  • "postedTime": "2019-08-24T14:15:22Z",
  • "deadlineTime": "2019-08-24T14:15:22Z"
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "customerId": "string",
  • "transactionId": "string",
  • "currency": "USD",
  • "amount": 0,
  • "acquirerReferenceNumber": "string",
  • "caseId": "string",
  • "reasonCode": "1000",
  • "category": "fraud",
  • "type": "information-request",
  • "status": "response-needed",
  • "postedTime": "2019-08-24T14:15:22Z",
  • "deadlineTime": "2019-08-24T14:15:22Z",
  • "rawResponse": "string",
  • "resolvedTime": "2019-08-24T14:15:22Z",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ],
  • "_embedded": [
    ]
}

Retrieve a dispute

Retrieve a dispute with specified identifier string.

Request
Security:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Deprecated

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200

Dispute was retrieved successfully.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

404

Resource was not found.

get/disputes/{id}
Request samples
$dispute = $client->disputes()->load('disputeId');
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "customerId": "string",
  • "transactionId": "string",
  • "currency": "USD",
  • "amount": 0,
  • "acquirerReferenceNumber": "string",
  • "caseId": "string",
  • "reasonCode": "1000",
  • "category": "fraud",
  • "type": "information-request",
  • "status": "response-needed",
  • "postedTime": "2019-08-24T14:15:22Z",
  • "deadlineTime": "2019-08-24T14:15:22Z",
  • "rawResponse": "string",
  • "resolvedTime": "2019-08-24T14:15:22Z",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ],
  • "_embedded": [
    ]
}

Create or update a Dispute with predefined ID

Create or update a Dispute with predefined identifier string.

Request
Security:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Deprecated

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json

Dispute resource.

transactionId
required
string

The dispute's transaction ID.

currency
required
string 3 characters

ISO 4217 alphabetic currency code.

amount
required
number <double>

The dispute amount.

acquirerReferenceNumber
string

The dispute's acquirer reference number.

caseId
string

The case ID for the dispute.

reasonCode
required
string

The dispute's reason code.

Enum: "1000" "10.1" "10.2" "10.3" "10.4" "10.5" "11.1" "11.2" "11.3" "12" … 156 more
type
required
string

The dispute's type.

Enum: "information-request" "first-chargeback" "second-chargeback" "arbitration" "fraud" "ethoca-alert" "verifi-alert"
status
required
string

The dispute's status.

Enum: "response-needed" "under-review" "forfeited" "won" "lost" "unknown"
postedTime
required
string <date-time>

Dispute posted time.

deadlineTime
string <date-time>

Dispute deadline time.

Responses
200

Dispute was updated.

201

Dispute was created.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

422

Invalid data was sent.

put/disputes/{id}
Request samples
application/json
{
  • "transactionId": "string",
  • "currency": "USD",
  • "amount": 0,
  • "acquirerReferenceNumber": "string",
  • "caseId": "string",
  • "reasonCode": "1000",
  • "type": "information-request",
  • "status": "response-needed",
  • "postedTime": "2019-08-24T14:15:22Z",
  • "deadlineTime": "2019-08-24T14:15:22Z"
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "customerId": "string",
  • "transactionId": "string",
  • "currency": "USD",
  • "amount": 0,
  • "acquirerReferenceNumber": "string",
  • "caseId": "string",
  • "reasonCode": "1000",
  • "category": "fraud",
  • "type": "information-request",
  • "status": "response-needed",
  • "postedTime": "2019-08-24T14:15:22Z",
  • "deadlineTime": "2019-08-24T14:15:22Z",
  • "rawResponse": "string",
  • "resolvedTime": "2019-08-24T14:15:22Z",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ],
  • "_embedded": [
    ]
}

Dispute createdWebhook

Request
Security:
Request Body schema: application/json

Dispute webhook request body resource.

disputeId
string

The dispute ID.

eventType
string (GlobalWebhookEventType)

Rebilly webhooks event type.

Enum: "aml-list-possibly-matched" "customer-created" "customer-merged" "customer-one-time-password-requested" "customer-redirected-offsite" "customer-returned" "customer-updated" "dispute-created" "dispute-modified" "experian-check-performed" … 54 more
object
object (Dispute)
id
string <= 50 characters

The dispute identifier string.

customerId
string

The dispute's customer ID.

transactionId
required
string

The dispute's transaction ID.

currency
required
string 3 characters

ISO 4217 alphabetic currency code.

amount
required
number <double>

The dispute amount.

acquirerReferenceNumber
string

The dispute's acquirer reference number.

caseId
string

The case ID for the dispute.

reasonCode
required
string

The dispute's reason code.

Enum: "1000" "10.1" "10.2" "10.3" "10.4" "10.5" "11.1" "11.2" "11.3" "12" … 156 more
category
string

The dispute's category.

Enum: "fraud" "unrecognized" "product-not-received" "product-unacceptable" "product-not-refunded" "duplicate" "subscription-canceled" "uncategorized"
type
required
string

The dispute's type.

Enum: "information-request" "first-chargeback" "second-chargeback" "arbitration" "fraud" "ethoca-alert" "verifi-alert"
status
required
string

The dispute's status.

Enum: "response-needed" "under-review" "forfeited" "won" "lost" "unknown"
postedTime
required
string <date-time>

Dispute posted time.

deadlineTime
string <date-time>

Dispute deadline time.

rawResponse
string

Dispute raw response from gateway.

resolvedTime
string <date-time>

Dispute resolved time.

createdTime
string <date-time>

Dispute created time.

updatedTime
string <date-time>

Dispute updated time.

Array of SelfLink (object) or TransactionLink (object) non-empty

The links related to resource.

Array of TransactionEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

Array of DisputeLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "dispute"
href
required
string

The link URL.

Responses
2xx

Return any 2xx status to indicate that the data was received successfully.

Request samples
application/json
{
  • "disputeId": "string",
  • "eventType": "aml-list-possibly-matched",
  • "_embedded": {
    },
  • "_links": [
    ]
}

Dispute modifiedWebhook

Request
Security:
Request Body schema: application/json

Dispute webhook request body resource.

disputeId
string

The dispute ID.

eventType
string (GlobalWebhookEventType)

Rebilly webhooks event type.

Enum: "aml-list-possibly-matched" "customer-created" "customer-merged" "customer-one-time-password-requested" "customer-redirected-offsite" "customer-returned" "customer-updated" "dispute-created" "dispute-modified" "experian-check-performed" … 54 more
object
object (Dispute)
id
string <= 50 characters

The dispute identifier string.

customerId
string

The dispute's customer ID.

transactionId
required
string

The dispute's transaction ID.

currency
required
string 3 characters

ISO 4217 alphabetic currency code.

amount
required
number <double>

The dispute amount.

acquirerReferenceNumber
string

The dispute's acquirer reference number.

caseId
string

The case ID for the dispute.

reasonCode
required
string

The dispute's reason code.

Enum: "1000" "10.1" "10.2" "10.3" "10.4" "10.5" "11.1" "11.2" "11.3" "12" … 156 more
category
string

The dispute's category.

Enum: "fraud" "unrecognized" "product-not-received" "product-unacceptable" "product-not-refunded" "duplicate" "subscription-canceled" "uncategorized"
type
required
string

The dispute's type.

Enum: "information-request" "first-chargeback" "second-chargeback" "arbitration" "fraud" "ethoca-alert" "verifi-alert"
status
required
string

The dispute's status.

Enum: "response-needed" "under-review" "forfeited" "won" "lost" "unknown"
postedTime
required
string <date-time>

Dispute posted time.

deadlineTime
string <date-time>

Dispute deadline time.

rawResponse
string

Dispute raw response from gateway.

resolvedTime
string <date-time>

Dispute resolved time.

createdTime
string <date-time>

Dispute created time.

updatedTime
string <date-time>

Dispute updated time.

Array of SelfLink (object) or TransactionLink (object) non-empty

The links related to resource.

Array of TransactionEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

Array of DisputeLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "dispute"
href
required
string

The link URL.

Responses
2xx

Return any 2xx status to indicate that the data was received successfully.

Request samples
application/json
{
  • "disputeId": "string",
  • "eventType": "aml-list-possibly-matched",
  • "_embedded": {
    },
  • "_links": [
    ]
}