Worldline Customer - Related 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 Customer - Related API
  contact: {}
servers:
- url: https://sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/card-issuing/api/v2
tags:
- name: Customer - Related
  description: Customer Related Api Controller
paths:
  /issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/accounts:
    get:
      tags:
      - Customer - Related
      summary: List accounts for account owner by external reference
      operationId: listAccountsForAccountOwnerByIssuerExtRef
      description: "This API enables all the accounts associated to the customer (cardholder)to be retrieved.\n\nThe customer must exist for the provided issuer.\nThe API returns all accounts linked to the given account owner for the provided issuer and sub-issuers if any, limited to the list of issuers allowed for the user.\n\n The interface provides the generic information (mainly master data) for managing the account. \nFor credit cards, payment mode and the due amount calculation is provided back."
      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: issuerCustomerExternalReference
        in: path
        description: Issuer Customer 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/ApiResponseEntityListAccount'
      security:
      - basic: []
      deprecated: false
  /issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/card-contracts:
    get:
      tags:
      - Customer - Related
      summary: List card contracts for cardholder by external reference
      operationId: listCardContractsForCardHolderByIssuerExtRef
      description: 'This API enables ll the card contracts associated to the cardholder to be retrieved.

        Information to be provided in input:

        - Issuer ID

        - Customer reference


        TThe customer must exist for the provided issuer.

        The API returns all card contracts linked to the given cardholder for the provided issuer and sub-issuers if any, limited to the list of issuers allowed for the user.'
      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: embed
        in: query
        description: Embedded Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - cards
            - cardIdentifiers
            - selectedModels
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: issuerCustomerExternalReference
        in: path
        description: Issuer Customer 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/ApiResponseEntityListCardContract'
      security:
      - basic: []
      deprecated: false
  /issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/contracts:
    get:
      tags:
      - Customer - Related
      summary: List contracts for a customer by external reference
      operationId: listContractsForContractOwnerByIssuerExtRef
      description: "This API allows to retrieve all contracts associated with a specific customer, regardless of their role in the contract (e.g., contract owner, card holder, account owner).\nInformation to be provided in input:\n•\tIssuer ID\n•\tThe customer for which information is requested : It can be provided by using the customer reference or the issuer customer external reference.\nThe customer must exist for the provided issuer.\nThe API returns all contracts linked to the given customer for the provided issuer and sub-issuers if any, limited to the list of issuers allowed for the user."
      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: issuerCustomerExternalReference
        in: path
        description: Issuer Customer 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/ApiResponseEntityListContract'
      security:
      - basic: []
      deprecated: false
  /issuers/{issuerId}/customers/{customerReference}/accounts:
    get:
      tags:
      - Customer - Related
      summary: List accounts for account owner
      operationId: listAccountsForAccountOwner
      description: "This API enables all the accounts associated to the customer (cardholder)to be retrieved.\n\nThe customer must exist for the provided issuer.\nThe API returns all accounts linked to the given account owner for the provided issuer and sub-issuers if any, limited to the list of issuers allowed for the user.\n\n The interface provides the generic information (mainly master data) for managing the account. \nFor credit cards, payment mode and the due amount calculation is provided back."
      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: customerReference
        in: path
        description: Customer 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/ApiResponseEntityListAccount'
      security:
      - basic: []
      deprecated: false
  /issuers/{issuerId}/customers/{customerReference}/addresses-and-subscriptions:
    post:
      x-wl-idempotent: true
      x-wl-lra-operation: true
      x-wl-lra-interface: true
      tags:
      - Customer - Related
      summary: Create address for a customer and subscribe to add-on
      operationId: createAddressAndSubscription
      description: "The API allows to create either a permanent address or a temporary address for the customer, identified with his reference, and to subscribe to an additional service (e.g. new letter, travel insurance) for a contract during all contract life cycle.\nAn address includes the following information:\n- the issuer address external reference\n- the label (e.g. MAIN_POSTAL_ADDRESS),\n- the type (mail address, phone number, email) and the corresponding data\n- the address usages\n- the start date (optional, by default, the current date is used)\n- the end date (conditional, only used when defining a temporary address)\n\nWhen creating a temporary address, If a temporary address already exists with an overlap on the activity period then only the newly created address will be kept and the old one will be removed.\n\nFor information, the main postal address is mandatory.\n\nA subscription to an additional service includes the following information:\n•\tThe identifier of the entity for which the add-on subscription is requested: Either the card contract by providing the card contract reference or the issuer external card contract reference, \nOR the account by providing the account reference or the issuer external account reference\n•\tThe corresponding reference of the additional service\n•\tThe service type reference defined at product level\n\nThe list of allowed additional services are defined on the product (e.g. PORTAL_ACCESS, ALERT, NOTIFICATION).\nDepending on the service type, the issuer can add additional parameters to the add-on service.\n\nAs a result:\n•\tThe new add-on subscription for the contract is available and can be unsubscribed during all contract life cycle\n•\tA fee can be generated and posted to the cardholder account if required for the product.\n\nIn return, the API provides the address reference calculated by the system.\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: customerReference
        in: path
        description: Customer 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/ApiResponseEntityCreateAddressAndSubscriptionResponse'
      security:
      - basic: []
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAddressAndSubscriptionRequest'
  /issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses-and-subscriptions:
    post:
      x-wl-idempotent: true
      x-wl-lra-operation: true
      tags:
      - Customer - Related
      summary: Create address for a customer and subscribe to add-on by external reference
      operationId: createAddressAndSubscriptionByCustomerIssuerExtRef
      description: "The API allows to create either a permanent address or a temporary address for the customer, identified with his reference, and to subscribe to an additional service (e.g. new letter, travel insurance) for a contract during all contract life cycle.\nAn address includes the following information:\n- the issuer address external reference\n- the label (e.g. MAIN_POSTAL_ADDRESS),\n- the type (mail address, phone number, email) and the corresponding data\n- the address usages\n- the start date (optional, by default, the current date is used)\n- the end date (conditional, only used when defining a temporary address)\n\nWhen creating a temporary address, If a temporary address already exists with an overlap on the activity period then only the newly created address will be kept and the old one will be removed.\n\nFor information, the main postal address is mandatory.\n\nA subscription to an additional service includes the following information:\n•\tThe identifier of the entity for which the add-on subscription is requested: Either the card contract by providing the card contract reference or the issuer external card contract reference, \nOR the account by providing the account reference or the issuer external account reference\n•\tThe corresponding reference of the additional service\n•\tThe service type reference defined at product level\n\nThe list of allowed additional services are defined on the product (e.g. PORTAL_ACCESS, ALERT, NOTIFICATION).\nDepending on the service type, the issuer can add additional parameters to the add-on service.\n\nAs a result:\n•\tThe new add-on subscription for the contract is available and can be unsubscribed during all contract life cycle\n•\tA fee can be generated and posted to the cardholder account if required for the product.\n\nIn return, the API provides the address reference calculated by the system.\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: issuerCustomerExternalReference
        in: path
        description: Issuer Customer 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/ApiResponseEntityCreateAddressAndSubscriptionResponse'
      security:
      - basic: []
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAddressAndSubscriptionRequest'
  /issuers/{issuerId}/customers/{customerReference}/card-contracts:
    get:
      tags:
      - Customer - Related
      summary: List card contracts for cardholder
      operationId: listCardContractsForCardHolder
      description: 'This API enables ll the card contracts associated to the cardholder to be retrieved.

        Information to be provided in input:

        - Issuer ID

        - Customer reference


        The customer must exist for the provided issuer.

        The API returns all card contracts linked to the given cardholder for the provided issuer and sub-issuers if any, limited to the list of issuers allowed for the user.'
      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: embed
        in: query
        description: Embedded Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - cards
            - cardIdentifiers
            - selectedModels
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: customerReference
        in: path
        description: Customer 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/ApiResponseEntityListCardContract'
      security:
      - basic: []
      deprecated: false
  /issuers/{issuerId}/customers/{customerReference}/contracts:
    get:
      tags:
      - Customer - Related
      summary: List contracts for a customer
      operationId: listContractsForContractOwner
      description: "This API allows to retrieve all contracts associated with a specific customer, regardless of their role in the contract (e.g., contract owner, card holder, account owner).\nInformation to be provided in input:\n•\tIssuer ID\n•\tThe customer for which information is requested : It can be provided by using the customer reference or the issuer customer external reference.\nThe customer must exist for the provided issuer.\nThe API returns all contracts linked to the given customer for the provided issuer and sub-issuers if any, limited to the list of issuers allowed for the user."
      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: customerReference
        in: path
        description: Customer 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/ApiResponseEntityListContract'
      security:
      - basic: []
      deprecated: false
components:
  schemas:
    CreateAddOnSubscriptionResponse:
      type: object
      required:
      - addonReference
      - serviceTypeReference
      properties:
        addonReference:
          type: string
          description: Name of the add-on
        subscriptionDate:
          type: string
          description: Date of the add-on subscription.
          format: date-time
        accountIdentifier:
          description: The accountIdentifier of the Account on which the subscription has been done
          allOf:
          - $ref: '#/components/schemas/AccountIdentifier'
        cardContractIdentifier:
          description: The cardContractIdentifier of the Card Contract on which the subscription has been done
          allOf:
          - $ref: '#/components/schemas/CardContractIdentifier'
      title: CreateAddOnSubscriptionResponse
    CardBlockingInformation:
      type: object
      required:
      - cardBlockingDateTime
      properties:
        cardBlockingDateTime:
          type: string
          format: date-time
          description: Date and time when the card has been blocked by our system
        blockAgent:
          type: string
          description: Operator who blocked the card (mandatory only if the card is blocked). It corresponds to the name of the user, referenced in our system, mentioned at the card blocking time.
        blockingReason:
          type: string
          description: 'Reason for blocking a card (mandatory only if the card is blocked)

            The list of blocking reasons is configurable per issuer (For example, LOST, STOLEN, FRAUDULENT …)'
        blockingReasonDetail:
          type: string
          description: 'Complementary information describing the defined blocking reason

            Free text'
        lostStolenDate:
          type: string
          format: date-time
          description: 'Date when the card has been lost or stolen

            This date is provided in addition to the blocking reason (required only if the card is blocked in a context of loss/theft)'
        lossPlace:
          type: string
          description: 'Place where the card has been lost

            Free text'
        lossCountry:
          type: string
          description: 'Country of card loss or steal

            Can be required in certain countries (e.g. french issuers with CB)

            Free text (not check on the provided value)'
        lastUsageDate:
          type: string
          format: date-time
          description: ' Date of last use of the card

            Example: for lost or stolen reason'
        lastUsagePlace:
          type: string
          description: 'Last place where the card has been used

            Example: for lost or stolen reason'
        lossCircumstances:
          type: string
          description: 'Description of the circumstances of the card loss

            Free text'
        lossReportedBy:
          type: string
          description: 'Person who has reported the card loss

            Free text'
        lossReportedVia:
          type: string
          description: 'How was reported the loss (channel)

            Free  text'
        fraudCode:
          type: string
          description: 'Fraud code can be used in the context of dispute management.

            Fraud code (free text) is provided in 

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