Disputes

Handle disputes (chargebacks and retrievals).

Retrieve a list of disputes

Retrieve a list of disputes.

SecuritySecretApiKey or JWT
Request
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.

Responses
200

A list of disputes was retrieved successfully.

Response Headers
Pagination-Total
integer

Total items count.

Pagination-Limit
integer

Items per page limit.

Pagination-Offset
integer

Pagination offset.

Response Schema: application/json
Array
currency
required
string = 3 characters

ISO 4217 alphabetic currency code.

amount
required
number <double>

The dispute amount.

transactionId
required
string

The dispute's transaction ID.

postedTime
required
string <date-time>

Dispute posted time.

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"
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
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

customerId
string

The dispute's customer ID.

acquirerReferenceNumber
string

The dispute's acquirer reference number.

caseId
string

The case ID for the dispute.

category
string

The dispute's category.

Enum: "fraud" "unrecognized" "product-not-received" "product-unacceptable" "product-not-refunded" "duplicate" "subscription-canceled" "uncategorized"
deadlineTime
string <date-time>

Dispute deadline time.

rawResponse
string

Dispute raw response from gateway.

resolvedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

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

The links related to resource.

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

The link type.

Value: "self"
href
required
string

The link URL.

Array of TransactionEmbed (object) non-empty

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

Array (non-empty)
Any of:

Transaction object.

object (Transaction)
401

Unauthorized access, invalid credentials were 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.

SecuritySecretApiKey or JWT
Request
Request Body schema: application/json

Dispute resource.

currency
required
string = 3 characters

ISO 4217 alphabetic currency code.

amount
required
number <double>

The dispute amount.

transactionId
required
string

The dispute's transaction ID.

postedTime
required
string <date-time>

Dispute posted time.

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"
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
acquirerReferenceNumber
string

The dispute's acquirer reference number.

caseId
string

The case ID for the dispute.

deadlineTime
string <date-time>

Dispute deadline time.

Responses
201

Dispute was created.

Response Schema: application/json
currency
required
string = 3 characters

ISO 4217 alphabetic currency code.

amount
required
number <double>

The dispute amount.

transactionId
required
string

The dispute's transaction ID.

postedTime
required
string <date-time>

Dispute posted time.

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"
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
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

customerId
string

The dispute's customer ID.

acquirerReferenceNumber
string

The dispute's acquirer reference number.

caseId
string

The case ID for the dispute.

category
string

The dispute's category.

Enum: "fraud" "unrecognized" "product-not-received" "product-unacceptable" "product-not-refunded" "duplicate" "subscription-canceled" "uncategorized"
deadlineTime
string <date-time>

Dispute deadline time.

rawResponse
string

Dispute raw response from gateway.

resolvedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

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

The links related to resource.

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

The link type.

Value: "self"
href
required
string

The link URL.

Array of TransactionEmbed (object) non-empty

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

Array (non-empty)
Any of:

Transaction object.

object (Transaction)
401

Unauthorized access, invalid credentials were 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.

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

The resource identifier string.

Responses
200

Dispute was retrieved successfully.

Response Schema: application/json
currency
required
string = 3 characters

ISO 4217 alphabetic currency code.

amount
required
number <double>

The dispute amount.

transactionId
required
string

The dispute's transaction ID.

postedTime
required
string <date-time>

Dispute posted time.

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"
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
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

customerId
string

The dispute's customer ID.

acquirerReferenceNumber
string

The dispute's acquirer reference number.

caseId
string

The case ID for the dispute.

category
string

The dispute's category.

Enum: "fraud" "unrecognized" "product-not-received" "product-unacceptable" "product-not-refunded" "duplicate" "subscription-canceled" "uncategorized"
deadlineTime
string <date-time>

Dispute deadline time.

rawResponse
string

Dispute raw response from gateway.

resolvedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

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

The links related to resource.

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

The link type.

Value: "self"
href
required
string

The link URL.

Array of TransactionEmbed (object) non-empty

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

Array (non-empty)
Any of:

Transaction object.

object (Transaction)
401

Unauthorized access, invalid credentials were 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.

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

The resource identifier string.

Request Body schema: application/json

Dispute resource.

currency
required
string = 3 characters

ISO 4217 alphabetic currency code.

amount
required
number <double>

The dispute amount.

transactionId
required
string

The dispute's transaction ID.

postedTime
required
string <date-time>

Dispute posted time.

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"
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
acquirerReferenceNumber
string

The dispute's acquirer reference number.

caseId
string

The case ID for the dispute.

deadlineTime
string <date-time>

Dispute deadline time.

Responses
200

Dispute was updated.

Response Schema: application/json
currency
required
string = 3 characters

ISO 4217 alphabetic currency code.

amount
required
number <double>

The dispute amount.

transactionId
required
string

The dispute's transaction ID.

postedTime
required
string <date-time>

Dispute posted time.

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"
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
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

customerId
string

The dispute's customer ID.

acquirerReferenceNumber
string

The dispute's acquirer reference number.

caseId
string

The case ID for the dispute.

category
string

The dispute's category.

Enum: "fraud" "unrecognized" "product-not-received" "product-unacceptable" "product-not-refunded" "duplicate" "subscription-canceled" "uncategorized"
deadlineTime
string <date-time>

Dispute deadline time.

rawResponse
string

Dispute raw response from gateway.

resolvedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

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

The links related to resource.

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

The link type.

Value: "self"
href
required
string

The link URL.

Array of TransactionEmbed (object) non-empty

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

Array (non-empty)
Any of:

Transaction object.

object (Transaction)
201

Dispute was created.

Response Schema: application/json
currency
required
string = 3 characters

ISO 4217 alphabetic currency code.

amount
required
number <double>

The dispute amount.

transactionId
required
string

The dispute's transaction ID.

postedTime
required
string <date-time>

Dispute posted time.

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"
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
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

customerId
string

The dispute's customer ID.

acquirerReferenceNumber
string

The dispute's acquirer reference number.

caseId
string

The case ID for the dispute.

category
string

The dispute's category.

Enum: "fraud" "unrecognized" "product-not-received" "product-unacceptable" "product-not-refunded" "duplicate" "subscription-canceled" "uncategorized"
deadlineTime
string <date-time>

Dispute deadline time.

rawResponse
string

Dispute raw response from gateway.

resolvedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

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

The links related to resource.

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

The link type.

Value: "self"
href
required
string

The link URL.

Array of TransactionEmbed (object) non-empty

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

Array (non-empty)
Any of:

Transaction object.

object (Transaction)
401

Unauthorized access, invalid credentials were 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

SecuritySecretApiKey or JWT
Request
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" "application-instance-disabled" "application-instance-disabled" "application-instance-enabled" "application-instance-enabled" "balance-transaction-settled" "credit-memo-applied" "credit-memo-created" "credit-memo-modified" "credit-memo-partially-applied" … 76 more
object
object (Dispute)
currency
required
string = 3 characters

ISO 4217 alphabetic currency code.

amount
required
number <double>

The dispute amount.

transactionId
required
string

The dispute's transaction ID.

postedTime
required
string <date-time>

Dispute posted time.

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"
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
id
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

customerId
string

The dispute's customer ID.

acquirerReferenceNumber
string

The dispute's acquirer reference number.

caseId
string

The case ID for the dispute.

category
string

The dispute's category.

Enum: "fraud" "unrecognized" "product-not-received" "product-unacceptable" "product-not-refunded" "duplicate" "subscription-canceled" "uncategorized"
deadlineTime
string <date-time>

Dispute deadline time.

rawResponse
string

Dispute raw response from gateway.

resolvedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

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

SecuritySecretApiKey or JWT
Request
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" "application-instance-disabled" "application-instance-disabled" "application-instance-enabled" "application-instance-enabled" "balance-transaction-settled" "credit-memo-applied" "credit-memo-created" "credit-memo-modified" "credit-memo-partially-applied" … 76 more
object
object (Dispute)
currency
required
string = 3 characters

ISO 4217 alphabetic currency code.

amount
required
number <double>

The dispute amount.

transactionId
required
string

The dispute's transaction ID.

postedTime
required
string <date-time>

Dispute posted time.

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"
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
id
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

customerId
string

The dispute's customer ID.

acquirerReferenceNumber
string

The dispute's acquirer reference number.

caseId
string

The case ID for the dispute.

category
string

The dispute's category.

Enum: "fraud" "unrecognized" "product-not-received" "product-unacceptable" "product-not-refunded" "duplicate" "subscription-canceled" "uncategorized"
deadlineTime
string <date-time>

Dispute deadline time.

rawResponse
string

Dispute raw response from gateway.

resolvedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

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": [
    ]
}