swagger: '2.0'
info:
description: 'The current set of APIs will be available in Q2 2026 on Worldline Global Issuing Platforms.
Additional APIs are under construction and planned to be available in 2026.'
version: 2.41.1
title: Worldline Card Issuing Account - AccountState Dispute API
contact: {}
host: sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/card-issuing
basePath: /api/v2
schemes:
- https
tags:
- name: Dispute
description: Dispute Api Controller
paths:
/issuers/{issuerId}/operations/{externalOperationReference}/disputes:
post:
tags:
- Dispute
summary: Create Dispute
operationId: createDispute
description: "This API is deprecated and is replaced by the API Create a dispute from a transaction.\nThe 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.\nSeveral actions can be performed :\n- Dispute only \n- Dispute + refund/redebit (full or partial)\n- Dispute + write-off (full or partial)\n- Dispute + fraud declaration\n- Dispute + event creation\n- Dispute + attach documents \n- Dispute + combination of above options\n\nMain data in input are :\n- 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.\n- 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)).\n\nIn 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."
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: externalOperationReference
in: path
description: External Operation Reference
required: true
type: string
- in: body
name: body
required: false
schema:
$ref: '#/definitions/CreateDisputeRequest'
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityCreateDisputeResponse'
security:
- basic: []
deprecated: true
/issuers/{issuerId}/disputes/{disputeFolderReference}:
get:
tags:
- Dispute
summary: Get the dispute information of the folder
operationId: getDisputeFolderInformation
description: 'The API returns the dispute folder information that matches the dispute folder identifier provided in input.
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 balance
- The transaction details including the reconciliation amount, the transaction type and merchant information
The response can also be enriched (if specified as embed 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. That corresponds to dispute cycle history. '
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: disputeFolderReference
in: path
description: Dispute Folder Reference
required: true
type: string
- name: embed
in: query
description: Embedded Fields
required: false
type: array
items:
type: string
enum:
- events
- postings
- documents
- messages
collectionFormat: multi
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityDispute'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/operations/{externalOperationReference}/dispute:
get:
tags:
- Dispute
summary: Get the dispute information of the operation identified by external operation reference
operationId: getDisputeFolderInfoByExternalOperationReference
description: 'This API can be used but will no longer evolve. It is recommended to use the ''Get the dispute information of the transaction'' API (GET /issuers/{issuerId}/transactions/{transactionId}/dispute). The API returns the dispute folder information if the transaction identified by an operation Identifier is disputed. If so, it provides access to the dispute content, including:
- General dispute folder details such as the dispute reason and status
- Cardholder information including card status and billing amount
- The issuer accounting balance
- Transaction details including the reconciliation amount, transaction type, and merchant information
The response may also be enriched (when embed fields are specified in the input) with additional data related to added events, performed postings, attached documents, and scheme messages, representing the dispute cycle history.
If the transaction is not disputed, a 404 response code is returned along with a status message indicating that no Dispute Folder has been found.'
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: externalOperationReference
in: path
description: External Operation Reference
required: true
type: string
- name: embed
in: query
description: Embedded Fields
required: false
type: array
items:
type: string
enum:
- events
- postings
- documents
- messages
collectionFormat: multi
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityDispute'
security:
- basic: []
deprecated: true
/issuers/{issuerId}/disputes/external-disputes/{issuerDisputeExternalReference}:
get:
tags:
- Dispute
summary: Get the dispute information of the folder identified by external reference
operationId: getDisputeFolderInfoByIssDisputeExtRef
description: 'The API returns the dispute folder information that matches the dispute folder identifier provided in input.
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 balance
- The transaction details including the reconciliation amount, the transaction type and merchant information
The response can also be enriched (if specified as embed 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. That corresponds to dispute cycle history.'
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: issuerDisputeExternalReference
in: path
description: Issuer Dispute External Reference
required: true
type: string
- name: embed
in: query
description: Embedded Fields
required: false
type: array
items:
type: string
enum:
- events
- postings
- documents
- messages
collectionFormat: multi
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityDispute'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/disputes/{disputeFolderReference}/postings:
post:
x-wl-idempotent: true
tags:
- Dispute
summary: Perform a posting (Refund or WriteOff) related to the Dispute Folder
operationId: createPosting
description: "Issuer can provide a posting operation to perform on the created dispute folder.\n\nPosting operation can be for example :\n•\tperform a refund towards the cardholder account\n•\tperform a write-off towards an issuer account (Profit and Loss, Fraud,..)\n\n\"Create a posting\" API allows an issuer to add postings for a given dispute folder.\n\nMain data in input is the dispute folder identifier and the parameters of the posting operation.\n\nIdempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once.The response will be retrieved directly from our system."
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: disputeFolderReference
in: path
description: disputeFolderReference
required: true
type: string
- in: body
name: body
required: false
schema:
$ref: '#/definitions/CreatePostingRequest'
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityCreatePostingResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/disputes/external-disputes/{issuerDisputeExternalReference}/postings:
post:
x-wl-idempotent: true
tags:
- Dispute
summary: Perform a posting related to the Dispute Folder by external reference
operationId: createPostingByIssDisputeExtRef
description: "Issuer can provide a posting operation to perform on the created dispute folder.\n\nPosting operation can be for example :\n•\tperform a refund towards the cardholder account\n•\tperform a write-off towards an issuer account (Profit and Loss, Fraud,..)\n\n\"Create a posting\" API allows an issuer to add postings for a given dispute folder.\n\nMain data in input is the dispute folder identifier and the parameters of the posting operation.\n\nIdempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once.The response will be retrieved directly from our system."
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: issuerDisputeExternalReference
in: path
description: Issuer Dispute External Reference
required: true
type: string
- in: body
name: body
required: false
schema:
$ref: '#/definitions/CreatePostingRequest'
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityCreatePostingResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/disputes/{disputeFolderReference}/events:
post:
x-wl-idempotent: true
tags:
- Dispute
summary: Create an Event in the Dispute Folder
operationId: createEvent
description: '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 cardholder.
The 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.
Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once.The response will be retrieved directly from our system.'
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: disputeFolderReference
in: path
description: disputeFolderReference
required: true
type: string
- in: body
name: body
required: false
schema:
$ref: '#/definitions/CreateEventRequest'
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityCreateEventResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/disputes/external-disputes/{issuerDisputeExternalReference}/events:
post:
x-wl-idempotent: true
tags:
- Dispute
summary: Create an Event in the Dispute Folder by external reference
operationId: createEventByIssDisputeExtRef
description: '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 cardholder.
The 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.
Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once.The response will be retrieved directly from our system.'
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: issuerDisputeExternalReference
in: path
description: Issuer Dispute External Reference
required: true
type: string
- in: body
name: body
required: false
schema:
$ref: '#/definitions/CreateEventRequest'
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityCreateEventResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/disputes/{disputeFolderReference}/documents:
post:
x-wl-idempotent: true
tags:
- Dispute
summary: Add an External Document to the Dispute Folder
operationId: createDocument
description: 'This API allows the issuer to attach a document to a dispute folder identified by his dispute folder identifier.
Supported documents types are in JPEG, TIFF and PDF format
The issuer must provide the data of the document in Base64 encoding format.
Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once.The response will be retrieved directly from our system.'
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: disputeFolderReference
in: path
description: disputeFolderReference
required: true
type: string
- in: body
name: body
required: false
schema:
$ref: '#/definitions/CreateDocumentRequest'
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityCreateDocumentResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/disputes/external-disputes/{issuerDisputeExternalReference}/documents:
post:
x-wl-idempotent: true
tags:
- Dispute
summary: Add an External Document to the Dispute Folder by external reference
operationId: createDocumentByIssDisputeExtRef
description: 'This API allows the issuer to attach a document to a dispute folder identified by his dispute folder identifier.
Supported documents types are in JPEG, TIFF and PDF format
The issuer must provide the data of the document in Base64 encoding format.
Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once.The response will be retrieved directly from our system.'
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: issuerDisputeExternalReference
in: path
description: Issuer Dispute External Reference
required: true
type: string
- in: body
name: body
required: false
schema:
$ref: '#/definitions/CreateDocumentRequest'
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityCreateDocumentResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/disputes/{disputeFolderReference}/generate-chargeback:
post:
x-wl-idempotent: true
tags:
- Dispute
summary: Generate a ChargeBack to the scheme by dispute reference
description: ' "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 support 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.
Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once.The response will be retrieved directly from our system.'
operationId: generateChargeback
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: disputeFolderReference
in: path
description: disputeFolderReference
required: true
type: string
- in: body
name: body
required: false
schema:
$ref: '#/definitions/GenerateChargebackRequest'
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '
# --- truncated at 32 KB (73 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wordline/refs/heads/main/openapi/wordline-dispute-api-openapi.yml