Dispute

DisputeWebhook POST

When a new dispute is opened or a dispute changes its status, Xsolla sends a webhook with the dispute type to the webhook URL. To receive this webhook, contact your Customer Success Manager or email csm@xsolla.com.

Request

Request Body schema: application/json

notification_type

required

string

Notification type.

action

required

string

Action type.

Enum:	Description
adding	A new dispute has been opened.
updating	A dispute’s status has changed.

required

object

Object with information about the transaction.

required

integer

Transaction ID.

date_create

required

string

Payment date.

required

object

Object with information about transaction amount.

amount required	number <float> Payment amount.
currency required	string Currency. Three-letter currency code per ISO 4217.

payment_method

required

string

Payment method.

Enum:	Description
credit_debit_card	Credit or debit card
paypal	PayPal

country_code

required

string

User’s country. Two-letter uppercase ISO 3166-1 alpha-2 country code.

external_id

string

Transaction external ID. Refer to the FAQs for detailed information.

required

object

Object with information about custom project settings.

project_id required	integer Project ID. You can find this parameter in your Publisher Account next to the name of the project.
merchant_id required	integer Merchant ID.

required

object

Object with information about a user.

id required	string User ID.
email	string User email.

required

object

Object with information about the dispute.

incoming_date

required

string

Date of the dispute opening according to the RFC 3339 standard.

reason

required

string

Reason for opening the dispute. Refer to documentation for description of groups of reasons.

Enum: "non_receipt" "not_as_described" "duplicate_processing" "paid_by_other_means" "incorrect_amount" "credit_not_processed" "general" "fraud" "cancelled_recurring" "cancelled_merchandise" "late_presentment" "no_authorization" "problem_with_remittance" "other"

type

required

string

Dispute type.

Enum:	Description
1st_time_chargeback	1st time chargeback.
2nd_time_chargeback	2nd time chargeback (pre-arbitration).
arbitration	Resolving a dispute between the issuing bank and the merchant when the 1st time chargeback and the 2nd time chargeback were rejected.
retrieval	A cardholder has requested payment details from the bank.
representment	The chargeback management team has sent the evidence to the payment system.
chargeback_reversal	Chargeback has been revoked.
representment_reversal	Chargeback has been revoked.
reimbursement	Refund has been made.
dispute	A cardholder has requested payment details from the bank.
chargeback	1st time chargeback.
claim	A dispute between a customer and a merchant in PayPal.
reimbursement_reversal	Chargeback has been revoked.
inquiry	A cardholder has requested payment details from the bank.
other	Used for chargeback types not covered by any other type.

status

required

string

Dispute status.

Enum:	Description
new	New
accepted	Accepted
no_actions_required	In progress
won	Won
lost	Lost

Responses

204

Return to indicate successful processing.

400

Return in case of an error in the provided information (e.g., a required parameter missing, failed authorization, etc.).

500

Return to indicate temporary errors with your servers.

Request samples

CURL
HTTP

curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 32c64a80d2527dc08906ae1891bac4489509b9f6' \
-d '{
  "notification_type": "dispute",
  "action": "adding",
  "transaction": {
    "id": 123456789,
    "date_create": "2023-08-24T10:21:00+04:00",
    "total": {
      "amount": 1,
      "currency": "EUR"
    },
    "payment_method": "credit_debit_card"
  },
  "settings": {
    "project_id": 18404,
    "merchant_id": 2340
  },
  "user": {
    "id": "1234567",
    "email": "email@example.com",
    "country_code": "US"
  },
  "dispute": {
    "incoming_date": "2024-01-25T01:02:03+04:00",
    "reason": "not_as_described",
    "type": "retrieval",
    "status": "new"
  }
}'

Response samples

application/json

{"error": {"code": "INVALID_USER",
"message": "Invalid user"
}
}