The Dispute object

The Dispute Object is used when a User requests a chargeback of transaction to their bank – in turn, their bank withdraws the funds from us and we will then repudiate the required funds from your client credit wallet.

Dispute process overview:

  1. A PayIn is completed successfully
  2. The end user contacts their bank to request a chargeback
  3. The bank contacts us and withdraws the funds automatically
  4. We create a Dispute object in the API – you will receive an email by default, and can also set up the usual Hooks if you like
  5. Along with the Dispute, we will also repudiate the funds from your credit wallet (the amount in the original wallet will therefore remain unchanged which is different to the previous process)
  6. If the Dispute is contestable, you are able to contest this Dispute and submit evidence to try to reverse the repudiation and reclaim the funds (note that you do not have to contest the full amount) – evidence might include a delivery note, a refund you’ve already done etc but will depend on the type of Dispute. The evidence is submitted as documents, just like for the current KYC process
  7. Once we’ve verified the Dispute documents, we will pass them on to the relevant bank, and they will either:
    • Accept the contest and refund the funds you had contested (we will then refund this amount to your credit wallet)
    • Reject the contest – in which case the Dispute will be closed as you have lost
    • Ask for further documents – in this case, we will reopen the Dispute and ask you to submit further evidence – check the StatusMessage field for more info
  8. In the event you have credit following a Dispute (because you lost, or didn’t contest the full amount), you can do a settlement transfer to transfer funds from the original wallet to the credit wallet if you wish – this is entirely optional and will depend on your workflow whether you want to impact the original wallet or not
  9. Any credit in your credit wallet will be deducted from your fees when you are billed each month before we send you your usual invoice

alt

Important notes:

  • You are strongly advised to use the available hooks to be notified (and therefore act on the changes from your side) of Dispute status changes (for example, in the case of a Dispute being reopened because more documents are required, you will not be notified by email – only via the hooks)
  • All contestable disputes have a date by which they can be contested – after this time, no further action is permitted from your side
  • Banks can sometimes issue a warning of a chargeback that may happen – in this case, we will still create a Dispute (with the DisputeType of “RETRIEVAL”) and require you to send various documents, however there will be no funds repudiated from your credit wallet in this case
  • Some Disputes are not contestable (they’ll have the DisputeType of “NOT_CONTESTABLE” as opposed to “CONTESTABLE”) – this means they’ll be closed just after being created and no further action is possible from your side

Parameters

Id
string

string:

Maximum length is 255 characters

The item's ID

CreationDate
timestamp

timestamp

When the item was created

Tag
string

string:

Maximum length is 255 characters

Custom data that you can add to this item

InitialTransactionId
string

string:

Maximum length is 255 characters

The initial transaction ID

InitialTransactionType
TransactionType

TransactionType:

PAYIN, TRANSFER, PAYOUT

The initial transaction type

ResultCode
string

string:

Maximum length is 255 characters

The result code

ResultMessage
string

string:

Maximum length is 255 characters

A verbal explanation of the ResultCode

DisputeReason
DisputeReason

DisputeReason:

View Sub-parameters

Info about the reason for the dispute

DisputeReason.DisputeReasonType
DisputeReasonType

DisputeReasonType:

DUPLICATE, FRAUD, PRODUCT_UNACCEPTABLE, UNKNOWN, OTHER, REFUND_CONVERSION_RATE, LATE_FAILURE_INSUFFICIENT_FUNDS, LATE_FAILURE_CONTACT_USER, LATE_FAILURE_BANKACCOUNT_CLOSED, LATE_FAILURE_BANKACCOUNT_INCOMPATIBLE, LATE_FAILURE_BANKACCOUNT_INCORRECT, AUTHORISATION_DISPUTED

The reason type for the dispute

The type of reason for the dispute

DisputeReason.DisputeReasonMessage
string

string:

Maximum length is 255 characters

More information about the reason for the dispute

Status
DisputeStatus

DisputeStatus:

CREATED, PENDING_CLIENT_ACTION, SUBMITTED, PENDING_BANK_ACTION, REOPENED_PENDING_CLIENT_ACTION, CLOSED

The status of the Dispute

The status of the dispute

StatusMessage
string

string:

Maximum length is 255 characters

Used to communicate information about the dispute status to you

DisputedFunds
Money

Money:

View Sub-parameters

The amount of fnds that were disputed

DisputedFunds.Currency
CurrencyIso

CurrencyIso:

EUR, USD, GBP, PLN, CHF, NOK, SEK, DKK, CAD, ZAR, XXX

ISO 4217 format

The currency - should be ISO_4217 format

DisputedFunds.Amount
int

int

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

ContestedFunds
Money

Money:

View Sub-parameters

The amount you wish to contest

ContestedFunds.Currency
CurrencyIso

CurrencyIso:

EUR, USD, GBP, PLN, CHF, NOK, SEK, DKK, CAD, ZAR, XXX

ISO 4217 format

The currency - should be ISO_4217 format

ContestedFunds.Amount
int

int

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

ContestDeadlineDate
timestamp

timestamp

The deadline by which you must contest the dispute (if you wish to contest it)

RepudiationId
string

string:

Maximum length is 255 characters

The ID of the associated repudiation transaction

{
"Id": "8494514",
"CreationDate": 12926321,
"Tag": "custom meta",
"InitialTransactionId": "1463496101",
"InitialTransactionType": "PAYIN",
"ResultCode": "000000",
"ResultMessage": "The transaction was successful",
"DisputeReason": {
"DisputeReasonType": "FRAUD",
"DisputeReasonMessage": "This was a fraudulent transaction"
},
"Status": "PENDING_CLIENT_ACTION",
"StatusMessage": "You must reupload your delivery proof",
"DisputedFunds": {
"Currency": "EUR",
"Amount": 12
},
"ContestedFunds": {
"Currency": "EUR",
"Amount": 12
},
"ContestDeadlineDate": 12327031,
"RepudiationId": "12639879"
}

View a Dispute

GET .../v2.01/ClientId

The ID of your client account

/disputes/DisputeId

The Id of a Dispute

/
  • View
  • Code
  • Run
  • View
  • Code
  • Run
GET .../disputes/:DisputeId/ HTTP/1.1
require_once("mangopay.php");

try {

$DisputeId = 12327031;

$Dispute = $Api->Disputes->Get($DisputeId);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
GET .../disputes// HTTP/1.1

Update a Dispute

This method is used to update the "Tag" of a dispute

PUT .../v2.01/ClientId

The ID of your client account

/disputes/DisputeId

The Id of a Dispute

/

Parameters

Tag
string

string:

Maximum length is 255 characters

optional

Custom data that you can add to this item

  • View
  • Code
  • Run
  • View
  • Code
  • Run
PUT .../disputes/:DisputeId/ HTTP/1.1
Body Parameters :
{
"Tag": "custom meta"
}
require_once("mangopay.php");

try {

$Dispute = new \MangoPay\Dispute();
$Dispute->Tag = "custom meta";
$Dispute->Id = 12327031;

$Result = $Api->Disputes->Update($Dispute);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
PUT .../disputes// HTTP/1.1
Body Parameters :
{
"Tag": ""
}

Close a Dispute

This method is used to close a "Dispute", effectively confirming that you do not wish to contest it. This action is optional, and once the "ContestDeadlineDate" passes, you will not be able to contest it anyway

PUT .../v2.01/ClientId

The ID of your client account

/disputes/DisputeId

The Id of a Dispute

/close/
  • View
  • Code
  • Run
  • View
  • Code
  • Run
PUT .../disputes/:DisputeId/close/ HTTP/1.1
require_once("mangopay.php");

try {

$Dispute = new \MangoPay\Dispute();
$Dispute->Id = 12327031;

$Result = $Api->Disputes->CloseDispute($Dispute);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
PUT .../disputes//close/ HTTP/1.1

Submit a Dispute

This method is used to contest a Dispute.

The "ContestedFunds" must be the same "Currency" as the "DisputedFunds", and the amount can be up to and including the "DisputedFunds".

PUT .../v2.01/ClientId

The ID of your client account

/disputes/DisputeId

The Id of a Dispute

/submit/

Parameters

ContestedFunds
Money

Money:

View Sub-parameters

optional

The amount you wish to contest

ContestedFunds.Currency
CurrencyIso

CurrencyIso:

EUR, USD, GBP, PLN, CHF, NOK, SEK, DKK, CAD, ZAR, XXX

ISO 4217 format

required

The currency - should be ISO_4217 format

ContestedFunds.Amount
int

int

required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

  • View
  • Code
  • Run
  • View
  • Code
  • Run
PUT .../disputes/:DisputeId/submit/ HTTP/1.1
Body Parameters :
{
"ContestedFunds": {
"Currency": "EUR",
"Amount": 12
}
}
require_once("mangopay.php");

try {

$Dispute = new \MangoPay\Dispute();
$Dispute->Id = 12327031;
$Dispute->ContestedFunds = new \MangoPay\Money();
$Dispute->ContestedFunds->Currency = "EUR";
$Dispute->ContestedFunds->Amount = 12;

$Result = $Api->Disputes->ContestDispute($Dispute);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
PUT .../disputes//submit/ HTTP/1.1
Body Parameters :
{
"ContestedFunds": {
"Currency": "",
"Amount":
}
}

Re-submit a Dispute

This method is used to resubmit a "Dispute" if it is reopened requiring more docs

PUT .../v2.01/ClientId

The ID of your client account

/disputes/DisputeId

The Id of a Dispute

/submit/
  • View
  • Code
  • Run
  • View
  • Code
  • Run
PUT .../disputes/:DisputeId/submit/ HTTP/1.1
require_once("mangopay.php");

try {

$Dispute = new \MangoPay\Dispute();
$Dispute->Id = 12327031;

$Result = $Api->Disputes->ResubmitDispute($Dispute);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
PUT .../disputes//submit/ HTTP/1.1

List a User's Disputes

GET .../v2.01/ClientId

The ID of your client account

/users/UserId

A Mangopay user's ID

/disputes/

Get parameters

Page
int

int

optional

The page number of results you wish to return

Per_Page
int

int

optional

The number of results to return per page

Sort
ColumnAndDirection

ColumnAndDirection:

The column to sort against and direction, separated by a :

optional

The column to sort against and direction - only CreationDate (or Date for the events) is available and ASC or DESC for the direction

BeforeDate
timestamp

timestamp

optional

To return only resources that have CreationDate BEFORE this date

AfterDate
timestamp

timestamp

optional

To return only resources that have CreationDate AFTER this date

DisputeType
DisputeType

DisputeType:

CONTESTABLE, NOT_CONTESTABLE, RETRIEVAL

The type of Dispute

optional

The type of dispute

Status
DisputeStatus

DisputeStatus:

CREATED, PENDING_CLIENT_ACTION, SUBMITTED, PENDING_BANK_ACTION, REOPENED_PENDING_CLIENT_ACTION, CLOSED

The status of the Dispute

optional

The status of this KYC/Dispute document

  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
GET .../users/:UserId/disputes/ HTTP/1.1
Get Parameters :
{
"Page": 1,
"Per_Page": 25,
"Sort": "CreationDate:DESC",
"BeforeDate": 1463440221,
"AfterDate": 1431817821,
"DisputeType": "CONTESTABLE",
"Status": "CREATED"
}
GET .../users//disputes/ HTTP/1.1
Get Parameters :
{
"Page": ,
"Per_Page": ,
"Sort": "",
"BeforeDate": ,
"AfterDate": ,
"DisputeType": "",
"Status": ""
}

List a Wallet's Disputes

GET .../v2.01/ClientId

The ID of your client account

/wallets/WalletId

The ID of a wallet

/disputes/

Get parameters

Page
int

int

optional

The page number of results you wish to return

Per_Page
int

int

optional

The number of results to return per page

Sort
ColumnAndDirection

ColumnAndDirection:

The column to sort against and direction, separated by a :

optional

The column to sort against and direction - only CreationDate (or Date for the events) is available and ASC or DESC for the direction

BeforeDate
timestamp

timestamp

optional

To return only resources that have CreationDate BEFORE this date

AfterDate
timestamp

timestamp

optional

To return only resources that have CreationDate AFTER this date

DisputeType
DisputeType

DisputeType:

CONTESTABLE, NOT_CONTESTABLE, RETRIEVAL

The type of Dispute

optional

The type of dispute

Status
DisputeStatus

DisputeStatus:

CREATED, PENDING_CLIENT_ACTION, SUBMITTED, PENDING_BANK_ACTION, REOPENED_PENDING_CLIENT_ACTION, CLOSED

The status of the Dispute

optional

The status of this KYC/Dispute document

  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
GET .../wallets/:WalletId/disputes/ HTTP/1.1
Get Parameters :
{
"Page": 1,
"Per_Page": 25,
"Sort": "CreationDate:DESC",
"BeforeDate": 1463440221,
"AfterDate": 1431817821,
"DisputeType": "CONTESTABLE",
"Status": "CREATED"
}
GET .../wallets//disputes/ HTTP/1.1
Get Parameters :
{
"Page": ,
"Per_Page": ,
"Sort": "",
"BeforeDate": ,
"AfterDate": ,
"DisputeType": "",
"Status": ""
}

List all Disputes

GET .../v2.01/ClientId

The ID of your client account

/disputes/

Get parameters

Page
int

int

optional

The page number of results you wish to return

Per_Page
int

int

optional

The number of results to return per page

Sort
ColumnAndDirection

ColumnAndDirection:

The column to sort against and direction, separated by a :

optional

The column to sort against and direction - only CreationDate (or Date for the events) is available and ASC or DESC for the direction

BeforeDate
timestamp

timestamp

optional

To return only resources that have CreationDate BEFORE this date

AfterDate
timestamp

timestamp

optional

To return only resources that have CreationDate AFTER this date

DisputeType
DisputeType

DisputeType:

CONTESTABLE, NOT_CONTESTABLE, RETRIEVAL

The type of Dispute

optional

The type of dispute

Status
DisputeStatus

DisputeStatus:

CREATED, PENDING_CLIENT_ACTION, SUBMITTED, PENDING_BANK_ACTION, REOPENED_PENDING_CLIENT_ACTION, CLOSED

The status of the Dispute

optional

The status of this KYC/Dispute document

  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
GET .../disputes/ HTTP/1.1
Get Parameters :
{
"Page": 1,
"Per_Page": 25,
"Sort": "CreationDate:DESC",
"BeforeDate": 1463440221,
"AfterDate": 1431817821,
"DisputeType": "CONTESTABLE",
"Status": "CREATED"
}
GET .../disputes/ HTTP/1.1
Get Parameters :
{
"Page": ,
"Per_Page": ,
"Sort": "",
"BeforeDate": ,
"AfterDate": ,
"DisputeType": "",
"Status": ""
}