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:
- A
PayIn
is completed successfully - The end user contacts their bank to request a chargeback
- The bank contacts us and withdraws the funds automatically
- 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 - 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)
- 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
- 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
- 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
- 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
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:
Maximum length is 255 characters
The item's ID
CreationDate
timestamp
When the item was created
Tag
string:
Maximum length is 255 characters
Custom data that you can add to this item
InitialTransactionId
string:
Maximum length is 255 characters
The initial transaction ID
InitialTransactionType
TransactionType:
PAYIN, TRANSFER, PAYOUT
The initial transaction type
ResultCode
string:
Maximum length is 255 characters
The result code
ResultMessage
string:
Maximum length is 255 characters
A verbal explanation of the ResultCode
DisputeReason
DisputeReason:
View Sub-parameters
Info about the reason for the dispute
DisputeReason.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, TRANSACTION_NOT_RECOGNIZED, PRODUCT_NOT_PROVIDED, CANCELED_REOCCURING_TRANSACTION, REFUND_NOT_PROCESSED
The reason type for the dispute
The type of reason for the dispute
DisputeReason.DisputeReasonMessage
string:
Maximum length is 255 characters
More information about the reason for the dispute
Status
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:
Maximum length is 255 characters
Used to communicate information about the dispute status to you
DisputedFunds
Money:
View Sub-parameters
The amount of funds that were disputed
DisputedFunds.Currency
Currency:
AED, AUD, CAD, CHF, CZK, DKK, EUR, GBP, HKD, JPY, NOK, PLN, SEK, USD, ZAR
The currency - should be ISO_4217 format
DisputedFunds.Amount
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:
View Sub-parameters
The amount you wish to contest
ContestedFunds.Currency
Currency:
AED, AUD, CAD, CHF, CZK, DKK, EUR, GBP, HKD, JPY, NOK, PLN, SEK, USD, ZAR
The currency - should be ISO_4217 format
ContestedFunds.Amount
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
The deadline by which you must contest the dispute (if you wish to contest it)
RepudiationId
string:
Maximum length is 255 characters
The ID of the associated repudiation transaction