Manage disputes

These APIs allow you to manage disputes raised via either API or dynamic flow.

The Dispute resource

This primary resource that you will be interacting with when managing your disputes.

idtext

Unique identifier of the dispute

transactionIdnumber

Card transaction ID

profileIdnumber

Profile ID

reasontext

Dispute reason description, you can find all the possible values here

descriptiontext

Dispute description submitted by customer

statustext

Dispute overall status, it is either ACTIVE or CLOSED

subStatustext

Dispute detailed status, you can check all the possible values below

statusMessagetext

Explanation for subStatus

createdAttext

Time when the dispute was created

createdBytext

Creator of the dispute, it is currently set to the user id

lastUpdatedAttext

Time when the dispute was last updated

canWithdrawboolean

Whether the dispute can be withdrawn

Table of available dispute subStatus and descriptions

Code	Description
SUBMITTED	Initial status
IN_REVIEW	The dispute is under review
ACCEPTED	The dispute is valid and has been accepeted for processing
CHARGEBACK_SUBMITTED	Chargeback has been requested for this dispute
REFUNDED	Refund has been processed for this dispute
REJECTED	The dispute is invalid
WITHDRAWN	The dispute has been withdrawn by the customer

Dispute Resource

{
  "id": "b4eae16c-b3a9-4327-b0bd-6a2ad430d803",
  "transactionId": 476873,
  "profileId": 14547572,
  "reason": "I was charged the wrong amount or currency",
  "description": "test dispute",
  "status": "CLOSED",
  "subStatus": "WITHDRAWN",
  "statusMessage": "Withdrawn",
  "createdAt": "2024-03-18T03:47:52.493Z",
  "createdBy": "9867661",
  "lastUpdatedAt": "2024-03-27T02:30:27.374Z",
  "canWithdraw": false
}

List disputes for a profile

GET /v3/spend/profiles/{{profileId}}/disputes?status=ACTIVE

Request

status (optional)text

Dispute status, can be either ACTIVE or CLOSED

transactionId (optional)number

Card transaction id

pageSize (optional)integer

The maximum number of disputes to return per page. This number can be between 10 - 100, and will default to 10

pageNumber (optional)integer

The page number to retrieve the next set of disputes. The number has to be greater than 1, and will default to 1

Response

Returns a list of disputes

Example Request

curl -X GET https://api.sandbox.transferwise.tech/v1/profiles/{{profileId}}/disputes?status=ACTIVE \
     -H 'Authorization: Bearer <your api token>'

Example Response

{
  "totalCount": 2,
  "disputes": [
    {
      "id": "51e2dc60-9e4b-4ff5-b917-b90cc5e1ecfb",
      "transactionId": 2040,
      "profileId": 16605997,
      "reason": "The order never arrived",
      "description": "never arrived dispute",
      "status": "ACTIVE",
      "subStatus": "SUBMITTED",
      "statusMessage": "Submitted",
      "createdAt": "2024-03-08T08:30:14.989Z",
      "createdBy": "6097861",
      "lastUpdatedAt": "2024-03-08T08:30:14.989Z",
      "canWithdraw": true
    },
    {
      "id": "9c5ca0cb-00d6-41f7-8214-8cfdb11388a7",
      "transactionId": 3405,
      "profileId": 16605997,
      "reason": "The order was cancelled",
      "description": "cancelled order dispute",
      "status": "ACTIVE",
      "subStatus": "SUBMITTED",
      "statusMessage": "Submitted",
      "createdAt": "2024-03-27T02:24:16.878Z",
      "createdBy": "6097861",
      "lastUpdatedAt": "2024-03-27T02:24:16.878Z",
      "canWithdraw": true
    }
  ]
}

Retrieve a dispute by ID

GET /v3/spend/profiles/{{profileId}}/disputes/{{disputeId}}

Retrieves a dispute based on the disputeId.

Response

Returns a Dispute.

Example Request

curl -X GET https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/disputes/{{disputeId}} \
     -H 'Authorization: Bearer <your api token>'

Example Response

{
    "id": "51e2dc60-9e4b-4ff5-b917-b90cc5e1ecfb",
    "transactionId": 2040,
    "profileId": 16605997,
    "reason": "The order never arrived",
    "description": "never arrived dispute",
    "status": "ACTIVE",
    "subStatus": "SUBMITTED",
    "statusMessage": "Submitted",
    "createdAt": "2024-03-08T08:30:14.989Z",
    "createdBy": "6097861",
    "lastUpdatedAt": "2024-03-08T08:30:14.989Z",
    "canWithdraw": true
}

Withdraw a dispute by ID

You can only withdraw a dispute if canWithdraw is set to true

PUT /v3/spend/profiles/{{profileId}}/disputes/{{disputeId}}/status

statusmoney

The value must be set to CLOSED

Response

Returns a Dispute.

Example Request

curl -X PUT https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/disputes/{{disputeId}}/status \
     -H 'Authorization: Bearer <your api token>' \
     -H 'Content-Type: application/json' \
     -d `{
       "status": "CLOSED"
     }`

Example Response

{
  "id": "51e2dc60-9e4b-4ff5-b917-b90cc5e1ecfb",
  "transactionId": 2040,
  "profileId": 16605997,
  "reason": "The order never arrived",
  "description": "never arrived dispute",
  "status": "CLOSED",
  "subStatus": "WITHDRAWN",
  "statusMessage": "Withdrawn",
  "createdAt": "2024-03-08T08:30:14.989Z",
  "createdBy": "6097861",
  "lastUpdatedAt": "2024-03-27T13:12:28.390Z",
  "canWithdraw": false
}