Worldline offers the issuer the possibility to capture the claim in several ways as illustrated below:
Dispute creation can be initiated by the WL dispute officer or directly triggered by API from the issuer application. Please find below a representation of the different use cases covered by our dispute API.
Worldline offers the possibility to perform several processes using a single call (create a dispute + additional actions such as posting) or perform unit processing per call. In order to follow-up the dispute process, API are available to get the dispute folder information based on its reference, or list the dispute folders for a given card.
Create a dispute and optionally posting, event or external document add (Deprecated)
This API is deprecated and is replaced by the API Create a dispute from a transaction.
The "Create a dispute" API allows an issuer to create a dispute folder in the system for a given operation.
This API enables the issuer to initiate the dispute from its application.
Several actions can be performed at the same time using this API:
- Dispute only
- Dispute + refund/redebit (full or partial)
- Dispute + write-off (full or partial)
- Dispute + fraud declaration
- Dispute + event creation
- Dispute + attach documents
- Dispute + combination of above options
Main data in input are :
- the external operation reference which can be retrieved using a search operation in the system, for example using the API retrieves list of operations for an account
- in option, several fields in the case additional actions have to be done besides the dispute folder creation (e.g. operation(s) posting, event(s) creation, add document(s))
In response, the created dispute folder identifier is provided back systematically; then depending on the additional requests, the response includes also the posting, event creation and documents add response.
API Links
Below an example in which a dispute creation is requested for transaction ID 10000000000264015 with COUNTERFEIT_CARD reason code, and additionally a write-off operation posting, a “comment” event creation and a document provided at the same time. In response, the dispute folder reference is provided back.
POST /api/v2/issuers/1234/operations/10000000000264015/disputes
Request data:
{
"disputeReason":"COUNTERFEIT_CARD",
"declareFraudIndicator":true,
"issuerDisputeExternalReference":"{{$randomUUID}}",
"disputePostings":[
{
"postingAmount":{
"value":7625,
"exponent":2,
"isoCode":"EUR"
},
"message":"Write off",
"immediateReimbursement":true,
"postingTypeReference":"ISSUER_ACCOUNT"
}
],
"disputeEvents":[
{
"type":"Comment",
"message":"Cardholder phone call"
}
],
"disputeDocuments":[
{
"data":"JVBERi0xLjcKJeA9eHJlZgo0OTEwOQolJUVPRgo=",
"type":"application/pdf",
"label":"test file",
"fileName":"test1.pdf"
}
]
}Response data:
{
"responseMetadata":{
"correlationId":"821c3c28-d5e6-4d05-93be-12efac2c7cc3",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2022-12-05T10:37:08.282+0100",
"timeTakenMs":680
},
"data":{
"disputeFolderIdentifier":{
"disputeFolderReference":"D-V-1234-2339-42",
"issuerDisputeExternalReference":"45f014d5-bc8a-4074-a707-8e20f272a9a3"
},
"disputePostings":[
{
"postingAmount":{
"value":7625,
"exponent":2,
"isoCode":"EUR"
},
"postingTypeReference":"ISSUER_ACCOUNT",
"creationDate":"2022-12-05T09:37:07.885+00:00"
}
],
"disputeEvents":[
{
"type":"Comment",
"creationDate":"2022-12-05T09:37:07.893+00:00"
}
],
"disputeDocuments":[
{
"fileName":"test1.pdf",
"creationDate":"2022-12-05T09:37:07.908+00:00"
}
]
}
}Generate a chargeback
The "generate chargeback" API allows an issuer to trigger a chargeback message to the scheme (VISA/MCI), the chargeback is done in synchronous mode.
Main information needed in input is:
- The dispute folder identifier
- The type of chargeback (partial or total for most of the cases)
- The chargeback scenario name used for VISA that supports the automated process (E-commerce fraud, duplicate Processing, Non-Receipt of Cash) or the chargeback reason code for MasterCard that can be found in MCI MPE file.
In response, the scheme case identifier is provided back.
API Links
The example below illustrates how a VISA chargeback is created and the scheme case ID provided in response.
POST /api/v2/issuers/1234/disputes/D-V-1234-2306-13/generate-chargeback
Request data:
{
"chargebackType":"FULL",
"chargebackScenario":"VISECOMFRAUD",
"chargebackDocument":{
"data":"iVBORw0KGgoAAAANSUhEUgAAAb4AAADQCAYAAAB4BAR3AAAAAXNSR0IArs4c
6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAABiPSURBVHhe
7Z0tlGPHEUYXGhoGGg….YGGhoaBgYGLgxcFmgYGBgYGBhoaBhoaBhoGLh519K381arGelJ/X
66695z+uysRqOfft39VVVX9Xv3UURE3uaXX84/yAgofCIib/Gf/ /wO0qDSHbNpUNQAAAABJRU5ErkJggg==",
"type":"image/jpeg",
"label":"new photo",
"fileName":"doc.jpeg"
}
}Response data:
{
"responseMetadata":{
"correlationId":"61d97e73-4917-4a29-a949-a5ae1a3398cd",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2022-12-05T11:13:05.502+0100",
"timeTakenMs":572
},
"data":{
"creationDate":"2022-12-05T11:13:05.501+0100",
"schemeCaseId":"6064286006"
}
}Retrieve dispute information for a given dispute folder
The API returns the dispute folder information that matches the dispute folder identifier provided in input.
This enables the dispute information to be retrieved:
- General dispute folder information including the dispute reason, the status
- Cardholder information including the card status and billing amount
- The issuer accounting balance
- The transaction details including the reconciliation amount, the transaction type and merchant information
The response can also be enriched (if specified as embedded fields in input) with additional data relative to the events added, the postings performed, the documents attached, and the messages sent or received from the scheme. This corresponds to the dispute cycle history.
API Links
GET /api/v2/issuers/{issuerId}/disputes/{disputeFolderReference}
GET /api/v2/issuers/{issuerId}/disputes/external-disputes/{issuerDisputeExternalReference}
An example below where events, messages and postings are specifically requested in the question.
GET /api/v2/issuers/1234/disputes/D-V-1234-2319-19?embed=events,postings,0messages
Response data:
{
"responseMetadata":{
"correlationId":"908fa9b9-99bc-4445-9d84-f1dd6b6b7283",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2022-12-05T10:55:17.648+0100",
"timeTakenMs":294
},
"data":{
"issuerId":"1234",
"disputeFolderIdentifier":{
"disputeFolderReference":"D-V-1234-2319-19",
"issuerDisputeExternalReference":"b7ead3d8-7fe1-41fd-890a-20ce9d3949f6"
},
"events":[
{
"type":"DISPUTE_INITIATE",
"message":"Dispute id : 13268",
"external":false,
"creationDate":"2022-11-15T18:06:04.097+00:00"
},
{
"type":"ASSOCIATE_TRANSACTION",
"message":"ATR Counter: 5, Purchase Inquiry ID: 3899975006, Credit Intent: true",
"creationDate":"2022-11-15T18:06:04.340+00:00"
},
{
"type":"LOCATE_TRANSACTION",
"message":"ROL transaction id : 3445758316",
"external":false,
"creationDate":"2022-11-15T18:06:01.433+00:00"
},
{
"type":"TRANSACTION_DETAILS",
"message":", RDR Eligible Indicator: false, Purchase Inquiry Eligible Indicator: true, Jurisdiction: DOM",
"external":false,
"creationDate":"2022-11-15T18:06:01.438+00:00"
},
{
"type":"CHARGEBACK_SUBMIT",
"message":"Chargeback scheme id : 13268",
"external":false,
"creationDate":"2022-11-15T18:06:04.399+00:00"
},
{
"type":"CREATE_CLAIM",
"message":"Scheme Case number : 1051342286",
"external":false,
"creationDate":"2022-11-15T18:06:03.336+00:00"
}
],
"postings":[
{
"postingAmount":{
"value":-21102,
"exponent":2,
"isoCode":"EUR"
},
"message":"First Presentment processed",
"immediateReimbursement":false,
"postingTypeReference":"Processing View",
"operationReference":"TPFPPT",
"creationDate":"2022-11-15T18:04:57.283+00:00"
}
],
"messages":[
{
"type":"FIRSTCHARGEBACK",
"status":"PENDING_SCHEME",
"creationDate":"2022-11-15T18:06:01.192+00:00",
"amount":{
},
"reasonCode":"13",
"reasonCodeDescription":"Consumer Dispute",
"reverseFlag":false,
"schemeCaseId":"1051342286"
},
{
"type":"ORIGINAL",
"status":"PROCESSED",
"creationDate":"2022-11-15T18:04:57.167+00:00",
"amount":{
"value":21102,
"exponent":2,
"isoCode":"EUR"
},
"reverseFlag":false,
"schemeCaseId":"1051342286"
}
],
"acquirerReferenceData":"74689342319113928021101",
"transactionType":"CASH_WITHDRAWAL",
"transactionTime":"2022-11-14T23:00:00.000+00:00",
"transactionAmount":{
"value":21101,
"exponent":2,
"isoCode":"BRL"
},
"reconciliationAmount":{
"value":21102,
"exponent":2,
"isoCode":"EUR"
},
"billingAmount":{
"value":21102,
"exponent":2,
"isoCode":"EUR"
},
"billingFees":{
"value":420,
"exponent":2,
"isoCode":"EUR"
},
"outstandingBalance":{
"value":21522,
"exponent":2,
"isoCode":"EUR"
},
"issuerAccountingBalance":{
"value":0,
"exponent":2,
"isoCode":"EUR"
},
"statusCode":"OPEN",
"reason":"COUNTERFEIT_CARD",
"creationDate":"2022-11-15T18:04:57.169+00:00",
"cardAcceptorName":"M.NAME-ATM",
"cardAcceptorCity":"RIO",
"cardAcceptorCountry":"BRAZIL",
"cardAcceptorIdCode":"CARD1002319 ID",
"cardAcceptorZipCode":"17520",
"userInCharge":"ADM - admin",
"cardIdentifier":{
"cardReference":"2000000000252082",
"issuerCardExternalReference":"b314e6df-c92d-4a36-83df-15f5d70e608f"
},
"lastMessageType":"FIRSTCHARGEBACK",
"lastMessageDate":"2022-11-15T18:06:01.192+00:00",
"lastMessageStatus":"PENDING_SCHEME"
}
}Retrieve dispute information for a given operation
The API returns the dispute folder information if the transaction identified by an operation Identifier is disputed.
If it is the case, this enables to see the content of the dispute information:
- General dispute folder information including the dispute reason, the status
- Cardholder information including the card status and billing amount
- The issuer accounting balance
- The transaction details including the reconciliation amount, the transaction type and merchant information
The response can also be enriched (if specified as embedded fields in input) with additional data relative to the events added, the postings performed, the documents attached, and the messages sent or received from the scheme. This corresponds to the dispute cycle history.
If the transaction is not disputed, the response code 404 is provided back with a status message indicating that no Dispute Folder has been found.
API Links
List dispute folders for a given card
The API returns the list of dispute folders for a given card, identified by his card identifier.
For each dispute folder provided, the content of the dispute is retrieved:
- General dispute folder information including the dispute reason, the status
- Cardholder information including the card status and billing amount
- The issuer accounting balance
- The transaction details including the reconciliation amount, the transaction type and merchant information
For each dispute folder, the response can also be enriched (if specified as embedded fields in input) with additional data relative to the events added, the postings performed, the documents attached, and the messages sent or received from the scheme. This corresponds to the dispute cycle history.
API Links
Create a posting
The issuer can provide a posting operation to be performed on the created dispute folder.
The posting operation can be for example:
- perform a refund towards the cardholder account
- perform a write-off towards an issuer account (Profit and Loss, Fraud,..)
"Create a posting" API allows an issuer to add postings for a given dispute folder.
Main data in input is the dispute folder identifier and the parameters of the posting operation.
API Links
Create an event
The issuer can provide an event to be added to the created dispute folder. This manual event will be added to events generated internally by our system. For example, the issuer can add an event to indicate that there is a communication from/to the cardholder.
"Create an event" API allows an issuer to add an event for a given dispute folder. Main data in input is the dispute folder identifier and the parameters of the event add operation.
API Links
Add external document to a dispute folder
This API allows the issuer to attach a document to a dispute folder identified by his dispute folder identifier.
Supported document types are JPEG, TIFF and PDF.
The issuer must provide the data of the document in Base64 encoding format.
API Links
Create a super folder
This API allows the creation of a super folder from a list of dispute folders.
The main input fields are:
- The issuer ID
- The list of dispute folder identifiers to be attached to the super folder : The dispute folder references must exist in our system and be associated to the same PAN.
The issuer can provide the name of the super folder to be created.
As a result, the super folder is created with its own reference calculated by our system.
The API response returns:
- The super folder reference
- The name of the super folder if provided in the request
API Links