Worldline Dispute API

openapi: 3.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 Dispute API
  contact: {}
servers:
- url: https://sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/card-issuing/api/v2
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."
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: WL-Origin
        in: header
        required: false
        schema:
          type: string
      - name: WL-Username
        in: header
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: externalOperationReference
        in: path
        description: External Operation Reference
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorApiResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorApiResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorErrorApiResponse'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayErrorApiResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEntityCreateDisputeResponse'
      security:
      - basic: []
      deprecated: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDisputeRequest'
  /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. '
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: WL-Origin
        in: header
        required: false
        schema:
          type: string
      - name: WL-Username
        in: header
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: disputeFolderReference
        in: path
        description: Dispute Folder Reference
        required: true
        schema:
          type: string
      - name: embed
        in: query
        description: Embedded Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - events
            - postings
            - documents
            - messages
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorApiResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorApiResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorErrorApiResponse'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayErrorApiResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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.'
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: WL-Origin
        in: header
        required: false
        schema:
          type: string
      - name: WL-Username
        in: header
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: externalOperationReference
        in: path
        description: External Operation Reference
        required: true
        schema:
          type: string
      - name: embed
        in: query
        description: Embedded Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - events
            - postings
            - documents
            - messages
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorApiResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorApiResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorErrorApiResponse'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayErrorApiResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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.'
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: WL-Origin
        in: header
        required: false
        schema:
          type: string
      - name: WL-Username
        in: header
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: issuerDisputeExternalReference
        in: path
        description: Issuer Dispute External Reference
        required: true
        schema:
          type: string
      - name: embed
        in: query
        description: Embedded Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - events
            - postings
            - documents
            - messages
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorApiResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorApiResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorErrorApiResponse'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayErrorApiResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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."
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: WL-Origin
        in: header
        required: false
        schema:
          type: string
      - name: WL-Username
        in: header
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: disputeFolderReference
        in: path
        description: disputeFolderReference
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorApiResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorApiResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorErrorApiResponse'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayErrorApiResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEntityCreatePostingResponse'
      security:
      - basic: []
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePostingRequest'
  /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."
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: WL-Origin
        in: header
        required: false
        schema:
          type: string
      - name: WL-Username
        in: header
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: issuerDisputeExternalReference
        in: path
        description: Issuer Dispute External Reference
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorApiResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorApiResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorErrorApiResponse'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayErrorApiResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEntityCreatePostingResponse'
      security:
      - basic: []
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePostingRequest'
  /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.'
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: WL-Origin
        in: header
        required: false
        schema:
          type: string
      - name: WL-Username
        in: header
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: disputeFolderReference
        in: path
        description: disputeFolderReference
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorApiResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorApiResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorErrorApiResponse'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayErrorApiResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEntityCreateEventResponse'
      security:
      - basic: []
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEventRequest'
  /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.'
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: WL-Origin
        in: header
        required: false
        schema:
          type: string
      - name: WL-Username
        in: header
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: issuerDisputeExternalReference
        in: path
        description: Issuer Dispute External Reference
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorApiResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorApiResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorErrorApiResponse'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayErrorApiResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEntityCreateEventResponse'
      security:
      - basic: []
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEventRequest'
  /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.'
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: WL-Origin
        in: header
        required: false
        schema:
          type: string
      - name: WL-Username
        in: header
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: disputeFolderReference
        in: path
        description: disputeFolderReference
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorApiResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorApiResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorErrorApiResponse'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayErrorApiResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEntityCreateDocumentResponse'
      security:
      - basic: []
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDocumentRequest'
  /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 doc

# --- truncated at 32 KB (82 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wordline/refs/heads/main/openapi/wordline-dispute-api-openapi.yml