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 Holding API
  contact: {}
host: sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/card-issuing
basePath: /api/v2
schemes:
- https
tags:
- name: Holding
paths:
  /acquiring/contract/v2.0/acquirers/{acquirerId}/holdings:
    get:
      tags:
      - Holding
      summary: Search holdings
      description: 'This operation retrieves a list of holdings. Terminated holdings are excluded.

        The acquirerId is a mandatory parameter.


        If there is a previous and/or next page the http response header will have a link (url) to this data

        '
      operationId: getHoldingOverviewList
      parameters:
      - name: acquirerId
        in: path
        description: Unique identification of the acquirer, determined by equensWorldline
        required: true
        schema:
          type: string
      - name: holdingId
        in: query
        description: 'Unique identification of the holding, determined by equensWorldline

          '
        schema:
          type: integer
          format: int32
      - name: holdingName
        in: query
        description: 'Name of the holding

          '
        schema:
          type: string
      - name: sortField
        in: query
        description: 'Sort field

          '
        schema:
          type: string
          enum:
          - HoldingId
          - HoldingName
      - name: sortOrder
        in: query
        description: 'Sort order

          '
        schema:
          type: string
          enum:
          - Ascending
          - Descending
      - name: pageSize
        in: query
        description: Page size
        schema:
          type: string
      - name: pageNumber
        in: query
        description: Page number
        schema:
          type: string
      - name: includeTerminated
        in: header
        description: Indicates whether terminated items should be included in the response of the GET call. Default value is 'false' (no terminated items included).
        schema:
          type: boolean
      responses:
        200:
          description: Successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HoldingListData'
              example:
              - contractIdentification:
                  acquirerId: '315000001'
                holdingId: 200
                holdingName: Event Payment Solutions
                status: Active
                address:
                  streetName: Stootblok
                  houseNumber: 14
                  postalCode: 3071AP
                  city: Rotterdam
                  countryCode: 528
                  contactPersonName: M. Scott
                  email: M.Scott@eventpaymentsolutions.com
                holdingDetailsURI: acquiring/contract/v2.0/acquirers/315000001/holdings/200
              - contractIdentification:
                  acquirerId: '315000001'
                holdingId: 300
                holdingName: Great Groceries
                status: Active
                address:
                  streetName: Utrechtsestraat
                  houseNumber: 17
                  postalCode: 1017VH
                  city: Amsterdam
                  countryCode: 528
                  contactPersonName: W. Kilbourne
                  email: W.Kilbourne@GreatGroceries.com
                holdingDetailsURI: acquiring/contract/v2.0/acquirers/315000001/holdings/300
        400:
          description: Invalid input provided
          content: {}
        401:
          description: Unauthorized
          content: {}
        403:
          description: Forbidden
          content: {}
        404:
          description: Resource not found
          content: {}
        500:
          description: Unexpected error
          content: {}
        502:
          description: Backend service problem
          content: {}
    post:
      tags:
      - Holding
      summary: Add a holding
      operationId: PostHolding
      parameters:
      - name: acquirerId
        in: path
        description: Unique identification of the acquirer, determined by equensWorldline
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/PostHolding'
          application/json:
            schema:
              $ref: '#/components/schemas/PostHolding'
          text/json:
            schema:
              $ref: '#/components/schemas/PostHolding'
          application/*+json:
            schema:
              $ref: '#/components/schemas/PostHolding'
        required: true
      responses:
        201:
          description: Change is processed with correlation id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostHoldingResponse'
        400:
          description: Invalid input provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        401:
          description: Unauthorized
          content: {}
        403:
          description: Forbidden
          content: {}
        404:
          description: Resource not found
          content: {}
        500:
          description: Unexpected error
          content: {}
        502:
          description: Backend service problem
          content: {}
  /acquiring/contract/v2.0/acquirers/{acquirerId}/holdings/{holdingId}:
    get:
      tags:
      - Holding
      summary: Retrieve a holding
      description: 'This operation retrieves a holding.

        '
      operationId: getHolding
      parameters:
      - name: acquirerId
        in: path
        description: Unique identification of the acquirer, determined by equensWorldline
        required: true
        schema:
          type: string
      - name: holdingId
        in: path
        description: 'Unique identification of the holding, determined by equensWorldline

          '
        required: true
        schema:
          type: integer
          format: int32
      - name: includeTerminated
        in: header
        description: Indicates whether terminated items should be included in the response of the GET call. Default value is 'false' (no terminated items included).
        schema:
          type: boolean
      responses:
        200:
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HoldingData'
              example:
                contractIdentification:
                  acquirerId: '315000001'
                  holdingId: 200
                basic:
                  acquirerName: Worldline Sandbox Bank
                  holdingName: Event Payment Solutions
                status:
                  status: Active
                  commencementDate: 2022-12-09
                addressDetailsURI: acquiring/contract/v2.0/acquirers/315000001/holdings/200/addresses
        400:
          description: Invalid input provided
          content: {}
        401:
          description: Unauthorized
          content: {}
        403:
          description: Forbidden
          content: {}
        404:
          description: Resource not found
          content: {}
        500:
          description: Unexpected error
          content: {}
        502:
          description: Backend service problem
          content: {}
    delete:
      tags:
      - Holding
      summary: Terminate a holding
      operationId: deleteHolding
      parameters:
      - name: acquirerId
        in: path
        description: Unique identification of the acquirer, determined by equensWorldline
        required: true
        schema:
          type: string
      - name: holdingId
        in: path
        description: 'Unique identification of the holding, determined by equensWorldline

          '
        required: true
        schema:
          type: integer
          format: int32
      responses:
        200:
          description: Termination of the holding is processed with correlation id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CorrelationResponse'
        400:
          description: Invalid input provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        401:
          description: Unauthorized
          content: {}
        403:
          description: Forbidden
          content: {}
        404:
          description: Resource not found
          content: {}
        500:
          description: Unexpected error
          content: {}
        502:
          description: Backend service problem
          content: {}
    patch:
      tags:
      - Holding
      summary: Update a holding
      description: "Fields that can be used: /basic/holdingName**\r\nOperations that can be used: **replace**\r\nSample request: \r\n\r\n    [\r\n       {\r\n           \"value\": \"MyHolding\",\r\n           \"path\": \"/basic/holdingName\",\r\n           \"op\": \"replace\"             \r\n       }\r\n    ]"
      operationId: patchHolding
      parameters:
      - name: acquirerId
        in: path
        description: Unique identification of the acquirer, determined by equensWorldline
        required: true
        schema:
          type: string
      - name: holdingId
        in: path
        description: 'Unique identification of the holding, determined by equensWorldline

          '
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json-patch+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Operation'
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Operation'
          text/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Operation'
          application/*+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Operation'
        required: false
      responses:
        200:
          description: Change is processed with correlation id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CorrelationResponse'
        400:
          description: Invalid input provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        401:
          description: Unauthorized
          content: {}
        403:
          description: Forbidden
          content: {}
        404:
          description: Resource not found
          content: {}
        500:
          description: Unexpected error
          content: {}
        502:
          description: Backend service problem
          content: {}
  /acquiring/contract/v2.0/acquirers/{acquirerId}/holdings/{holdingId}/addresses:
    get:
      tags:
      - Holding
      summary: Retrieve the addresses of a holding
      description: 'This operation retrieves addresses of a holding.

        '
      operationId: getHoldingAddresses
      parameters:
      - name: acquirerId
        in: path
        description: Unique identification of the acquirer, determined by equensWorldline
        required: true
        schema:
          type: string
      - name: holdingId
        in: path
        description: 'Unique identification of the holding, determined by equensWorldline

          '
        required: true
        schema:
          type: integer
          format: int32
      - name: includeTerminated
        in: header
        description: Indicates whether terminated items should be included in the response of the GET call. Default value is 'false' (no terminated items included).
        schema:
          type: boolean
      responses:
        200:
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HoldingAddressData'
              example:
                contractIdentification:
                  acquirerId: '315000001'
                  holdingId: 200
                addresses:
                - addressType: Business
                  streetName: Stootblok
                  houseNumber: 14
                  postalCode: 3071AP
                  city: Rotterdam
                  countryCode: 528
                  contactPersonName: M. Scott
                  email: M.Scott@eventpaymentsolutions.com
                  communicationLanguage: eng
                  communicationPreference: 3
        400:
          description: Invalid input provided
          content: {}
        401:
          description: Unauthorized
          content: {}
        403:
          description: Forbidden
          content: {}
        404:
          description: Resource not found
          content: {}
        500:
          description: Unexpected error
          content: {}
        502:
          description: Backend service problem
          content: {}
components:
  schemas:
    PostHolding:
      type: object
      properties:
        basic:
          $ref: '#/components/schemas/PostHoldingBasic'
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorData'
    AddressDetails:
      required:
      - addressType
      - city
      - countryCode
      type: object
      properties:
        addressType:
          type: string
          description: Type of the address. Values [Business, Chargeback, Creditor, Debtor, Invoice, Location, Postal, Private]
          example: Business
        streetName:
          type: string
          description: Street name and house number of the address. In case of a Dutch address only Street name
          example: Stootblok
        houseNumber:
          type: integer
          description: House number. Only used for Dutch addresses
          format: int32
          example: 14
        houseAddition:
          type: string
          description: House number addition. Only used for Dutch addresses
          example: bis
        postalCode:
          type: string
          description: Postal code of the address
          example: 3071AP
        city:
          type: string
          description: City of the address
          example: Rotterdam
        region:
          type: string
          description: Region of the address. Only applicable for specific countries
          example: Zuid-Holland
        countryCode:
          type: string
          description: Country of the address according to ISO 3166-1 (numeric-3)
          example: '528'
        departmentName:
          type: string
          description: Department of the contact person registered with the address
          example: Finance
        contactPersonName:
          type: string
          description: Name of the contact person registered with the address
          example: M. Scott
        postalRoom:
          type: string
          description: Postal room of the contact person registered with the address
          example: 2N.17
        telephoneNumber:
          type: string
          description: Telephone number of contact person registered with the address
          example: +31-63864055
        faxNumber:
          type: string
          description: Fax number of the contact person registered with the address
          example: +31-24683905
        email:
          type: string
          description: E-mail address of the contact person registered with the address
          example: M.Scott@eventpaymentsolutions.com
        communicationLanguage:
          type: string
          description: Preferred communication language of the contact person registered with the address accrding to ISO 639-2 (alphanumeric-3)
          example: eng
        communicationPreference:
          type: integer
          description: Preferred communication type of the contact person registered with the address. Values [1 = Post, 2 = Fax, 3 = E-mail]
          format: int32
          example: 3
    HoldingStatus:
      type: object
      properties:
        status:
          type: string
          description: The status of the holding. Values [Active]
        commencementDate:
          type: string
          description: Date at which the holding was registered
    PostHoldingResponse:
      type: object
      properties:
        correlationId:
          type: string
          format: uuid
        contractIdentification:
          $ref: '#/components/schemas/MerchantIdentificationResponse'
    MerchantIdentificationResponse:
      type: object
      properties:
        acquirerId:
          type: string
          description: Unique identification of the acquirer, determined by equensWorldline
        holdingId:
          type: string
          description: Unique identification of the holding, determined by equensWorldline
        merchantId:
          type: string
          description: Unique identification of the merchant, determined by the acquirer
        contractId:
          type: string
          description: Unique identification of the contract, determined by the acquirer
          example: '10011'
        siteId:
          type: integer
          description: Unique identification of the site within the contract
          format: int64
        cardAcceptorId:
          type: string
          description: Unique identification of the site in accordance with payment scheme rules. Some Dutch acquirers have a waiver not to fill this field. In that case it contains the merchant ID
        terminalId:
          type: string
          description: Identification of the terminal. Within the Dutch model a terminal ID uniquely identifies one specific physical device. Within other terminal models the terminal ID is only considered unique within the context of its own site (card acceptor ID)
    PostHoldingBasic:
      type: object
      properties:
        holdingName:
          type: string
          description: Name of the holding
          example: Event Payment Solutions
    HoldingListData:
      type: object
      properties:
        contractIdentification:
          type: object
          properties:
            acquirerId:
              type: string
              description: Unique identification of the acquirer, determined by equensWorldline
              example: '315000001'
        holdingId:
          type: integer
          description: Unique identification of the holding, determined by equensWorldline
          format: int32
          example: 200
        holdingName:
          type: string
          description: Name of the holding
          example: Event Payment Solutions
        status:
          type: string
          description: The status of this entity. Values [Active]
          example: Active
        address:
          $ref: '#/components/schemas/Address'
        holdingDetailsURI:
          type: string
          description: URI to get the holding details
          example: acquiring/contract/v2.0/acquirers/XXX/holdings/XXX
    CorrelationResponse:
      type: object
      properties:
        correlationId:
          type: string
          description: Unique ID that was generated for the specific change
          format: uuid
    HoldingContractIdentification:
      type: object
      properties:
        acquirerId:
          type: string
          description: Unique identification of the acquirer, determined by equensWorldline
        holdingId:
          type: string
          description: Unique identification of the holding, determined by equensWorldline
    HoldingData:
      type: object
      properties:
        contractIdentification:
          $ref: '#/components/schemas/HoldingContractIdentification'
        basic:
          $ref: '#/components/schemas/HoldingBasic'
        status:
          $ref: '#/components/schemas/HoldingStatus'
        addressDetailsURI:
          type: string
          description: URI to get the holding address details
          example: acquiring/contract/v2.0/acquirers/XXX/holdings/XXX/addresses
    HoldingAddressData:
      type: object
      properties:
        contractIdentification:
          $ref: '#/components/schemas/HoldingContractIdentification'
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/AddressDetails'
    ErrorData:
      type: object
      properties:
        code:
          type: string
          description: Unique code of the error as returned by the system handling the request
        keyword:
          type: string
          description: JSON keyword from the request message that triggered the error
        errorMessage:
          type: string
          description: Message explaining the error
    Address:
      type: object
      properties:
        streetName:
          type: string
          description: Street name and house number of the address. In case of a Dutch address only Street name
          example: Stootblok
        houseNumber:
          type: integer
          description: House number. Only used for Dutch addresses
          format: int32
          example: 14
        houseAddition:
          type: string
          description: House number addition. Only used for Dutch addresses
          example: bis
        postalCode:
          type: string
          description: Postal code of the address
          example: 3071AP
        city:
          type: string
          description: City of the address
          example: Rotterdam
        region:
          type: string
          description: Region of the address. Only applicable for specific countries
          example: Zuid-Holland
        countryCode:
          type: string
          description: Country of the address according to ISO 3166-1 (numeric-3)
          example: '528'
        contactPersonName:
          type: string
          description: Name of the contact person registered with the address
          example: M. Scott
        telephoneNumber:
          type: string
          description: Telephone number of contact person registered with the address
          example: 0883855111
        email:
          type: string
          description: E-mail address of the contact person registered with the address
          example: M.Scott@eventpaymentsolutions.com
    Operation:
      type: object
      properties:
        value:
          type: object
          properties: {}
        path:
          type: string
          description: 'A pointer to a specific value (field) that needs to be changed


            examples /basic/merchantCategoryCode, brands/0/brandParameters/allowedServices/refundService

            '
        op:
          type: string
          description: 'The following operations are implemented

            - replace - change the value of a specific field

            - remove -  remove the value of a specific field (only allowed for optional fields)

            '
        from:
          type: string
          description: Not elevant for currently supported operations
    HoldingBasic:
      type: object
      properties:
        acquirerName:
          type: string
          description: Name of the acquirer
        holdingName:
          type: string
          description: Name of the holding
securityDefinitions:
  basic:
    type: oauth2
    flow: application
    tokenUrl: https://sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/token