Worldline Direct Debit 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 Direct Debit API
  contact: {}
servers:
- url: https://sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/card-issuing/api/v2
tags:
- name: Direct Debit
  description: Direct Debit Api Controller
paths:
  /issuers/{issuerId}/direct-debits:
    post:
      x-wl-idempotent: true
      tags:
      - Direct Debit
      summary: Create a direct debit instruction
      description: 'This API enables a direct debit note to be requested by debiting a customer bank account (inhouse or external) to increase the open to buy of the card account (for a particular purchase).


        As a result, the direct debit is generated and after n business days (issuer configuration), the card account is paid with the requested amount (the total amount due for this card account is paid first).

        The API returns the unique Direct Debit EndToEnd Identifier generated by our system and the direct debit status.


        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: createDirectDebit
      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
      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/ApiResponseEntityCreateDirectDebitResponse'
      security:
      - basic: []
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDirectDebitRequest'
        required: true
  /issuers/{issuerId}/direct-debits/{endToEndId}:
    get:
      tags:
      - Direct Debit
      summary: Retrieve a direct debit
      description: This API enables an already created direct debit instruction to be retrieved by providing in input the Direct debit E2E Identifier and the reject reason.
      operationId: retrieveDirectDebit
      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: endToEndId
        in: path
        description: DD identifier
        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:
            - statusHistory
      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/ApiResponseEntityDirectDebit'
      security:
      - basic: []
      deprecated: false
  /issuers/{issuerId}/direct-debits/{endToEndId}/cancel:
    post:
      tags:
      - Direct Debit
      summary: Cancel direct debit
      description: 'This API enables a direct debit instruction to be cancelled by providing in input the Direct debit E2E Identifier.

        The cancellation is possible for Direct debit not collected yet (sent to the bank).'
      operationId: cancelDirectDebit
      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: endToEndId
        in: path
        description: DD identifier
        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/ApiResponseEntityCancelDirectDebitResponse'
      security:
      - basic: []
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelDirectDebitRequest'
components:
  schemas:
    InternalServerErrorResponseMetadata:
      type: object
      required:
      - correlationId
      - responseDateTime
      - statusCode
      - statusMessage
      properties:
        correlationId:
          type: string
          description: Correlation Identifier
        responseDateTime:
          type: string
          example: format:yyyy-MM-dd'T'HH:mm:ss.SSSZ
          description: Timestamp when response date was generated
        statusCode:
          type: integer
          format: int32
          example: 500
          description: HTTP status code
        statusMessage:
          type: string
          example: Internal server error
          description: Executed REST API status message
      title: InternalServerErrorResponseMetadata
    CancelDirectDebitRequest:
      type: object
      properties:
        rejectionReason:
          type: string
          description: Reason for cancelling the direct debit (free text)
      title: CancelDirectDebitRequest
    ApiResponseEntityCreateDirectDebitResponse:
      x-wl-api-response: true
      type: object
      required:
      - responseMetadata
      properties:
        responseMetadata:
          description: Response metadata
          allOf:
          - $ref: '#/components/schemas/ResponseMetadata'
        data:
          description: Response data
          allOf:
          - $ref: '#/components/schemas/CreateDirectDebitResponse'
      description: Issuer response entity
      title: ApiResponseEntityCreateDirectDebitResponse
    BadRequestErrorApiResponse:
      type: object
      required:
      - responseMetadata
      properties:
        responseMetadata:
          allOf:
          - $ref: '#/components/schemas/BadRequestResponseMetadata'
      title: BadRequestErrorApiResponse
    ForbiddenErrorApiResponse:
      type: object
      required:
      - responseMetadata
      properties:
        responseMetadata:
          allOf:
          - $ref: '#/components/schemas/ForbiddenResponseMetadata'
      title: ForbiddenErrorApiResponse
    BadGatewayErrorApiResponse:
      type: object
      required:
      - responseMetadata
      properties:
        responseMetadata:
          allOf:
          - $ref: '#/components/schemas/BadGatewayResponseMetadata'
      title: BadGatewayErrorApiResponse
    Links:
      type: object
      required:
      - self
      properties:
        self:
          type: string
          example: /x/{x}?x=x
          description: Service method URL
        next:
          type: string
          example: /x/{x}?page[offset]=2
          description: URL pagination query parameter next page
      title: Links
    UnauthorizedErrorApiResponse:
      type: object
      required:
      - responseMetadata
      properties:
        responseMetadata:
          allOf:
          - $ref: '#/components/schemas/UnauthorizedResponseMetadata'
      title: UnauthorizedResponseMetadata
    DirectDebitIdentifier:
      type: object
      properties:
        endToEndId:
          type: string
          description: DD identifier
      title: DirectDebitIdentifier
    NotFoundResponseMetadata:
      type: object
      required:
      - correlationId
      - responseDateTime
      - statusCode
      - statusMessage
      properties:
        correlationId:
          type: string
          description: Correlation Identifier
        responseDateTime:
          type: string
          example: format:yyyy-MM-dd'T'HH:mm:ss.SSSZ
          description: Timestamp when response date was generated
        statusCode:
          type: integer
          format: int32
          example: 404
          description: HTTP status code
        statusMessage:
          type: string
          example: Not found
          description: Executed REST API status message
      title: NotFoundResponseMetadata
    UnauthorizedResponseMetadata:
      type: object
      required:
      - correlationId
      - responseDateTime
      - statusCode
      - statusMessage
      properties:
        correlationId:
          type: string
          description: Correlation Identifier
        responseDateTime:
          type: string
          example: format:yyyy-MM-dd'T'HH:mm:ss.SSSZ
          description: Timestamp when response date was generated
        statusCode:
          type: integer
          format: int32
          example: 401
          description: HTTP status code
        statusMessage:
          type: string
          example: Unauthorized
          description: Executed REST API status message
      title: UnauthorizedResponseMetadata
    DirectDebit:
      type: object
      properties:
        issuerId:
          type: string
          description: Issuer identifier (unique per platform)
        directDebitIdentifier:
          description: Unique identifier of the Direct Debit
          allOf:
          - $ref: '#/components/schemas/DirectDebitIdentifier'
        overPaymentAccountIdentifier:
          description: 'Identifier of the overpayment account '
          allOf:
          - $ref: '#/components/schemas/AccountIdentifier'
        payingAccountIdentifier:
          description: Identifier of the paying account
          allOf:
          - $ref: '#/components/schemas/AccountIdentifier'
        sci:
          type: string
          description: SEPA Creditor Identifier (for SEPA DD)
        mandateUmr:
          type: string
          description: Unique Mandate Reference (for SEPA DD)
        amount:
          description: Direct Debit due amount
          allOf:
          - $ref: '#/components/schemas/Amount'
        sepaIndicator:
          type: boolean
          description: Indicates if DD is SEPA or no
        creationDate:
          type: string
          format: date-time
          description: Creation Date of the DD
        extractType:
          type: string
          description: Extract type
        status:
          type: string
          description: DD Status
        dueDate:
          type: string
          format: date-time
          description: Due date
        sequenceType:
          type: string
          description: Sequence type
        remittanceInfo:
          type: string
          description: Remittance info
        rejectionReason:
          type: string
          description: Rejection Reason (if SDD is rejected)
        debtorBankFee:
          description: Debtor Bank Fee
          allOf:
          - $ref: '#/components/schemas/Amount'
        creditorBankFee:
          description: Creditor Bank Fee
          allOf:
          - $ref: '#/components/schemas/Amount'
        cancellationDate:
          type: string
          format: date-time
          description: The date when the Direct Debit order was canceled
        statusHistory:
          description: 'Debtor Bank Fee.

            _Embedded property, only filled when available for the endpoint and explicitly requested in the ''embed'' query parameter._'
          type: array
          items:
            $ref: '#/components/schemas/DirectDebitStatusHistory'
        paymentTrigger:
          type: string
          description: "Indicates how the payment is triggered \nThe possible values are :\n- ON_DEMAND\n- CYCLIC (related to monthly cycle closure)\n- ON_TRANSACTION"
        paymentReason:
          type: string
          description: "Reason why the payment is triggered \nThe list of possible payment reasons is configurable per issuer."
      title: DirectDebit
    BadRequestResponseMetadata:
      type: object
      required:
      - correlationId
      - responseDateTime
      - statusCode
      - statusMessage
      properties:
        correlationId:
          type: string
          description: Correlation Identifier
        responseDateTime:
          type: string
          example: format:yyyy-MM-dd'T'HH:mm:ss.SSSZ
          description: Timestamp when response date was generated
        statusCode:
          type: integer
          format: int32
          example: 400
          description: HTTP status code
        statusMessage:
          type: string
          example: Bad request
          description: Executed REST API status message
      title: BadRequestResponseMetadata
    NotFoundErrorApiResponse:
      type: object
      required:
      - responseMetadata
      properties:
        responseMetadata:
          allOf:
          - $ref: '#/components/schemas/NotFoundResponseMetadata'
      title: NotFoundErrorApiResponse
    DirectDebitStatusHistory:
      type: object
      properties:
        status:
          type: string
          description: 'Status of the direct debit transfer on the particular status date '
        statusDate:
          type: string
          format: date-time
          description: Date of the direct debit status change
        username:
          type: string
          description: Name of the user who requested to create or cancel the direct debit
        origin:
          type: string
          description: Origin used when the direct debit was requested or cancelled.
      title: DirectDebitStatusHistory
    BadGatewayResponseMetadata:
      type: object
      required:
      - correlationId
      - responseDateTime
      - statusCode
      - statusMessage
      properties:
        correlationId:
          type: string
          description: Correlation Identifier
        responseDateTime:
          type: string
          example: format:yyyy-MM-dd'T'HH:mm:ss.SSSZ
          description: Timestamp when response date was generated
        statusCode:
          type: integer
          format: int32
          example: 502
          description: HTTP status code
        statusMessage:
          type: string
          example: Bad Gateway
          description: Executed REST API status message
      title: BadGatewayResponseMetadata
    Amount:
      type: object
      required:
      - value
      - exponent
      - isoCode
      properties:
        value:
          type: integer
          format: int64
          description: Integer amount value. Ex. if it is two hundred euros and 17 cents, then amount value is 20017 (exponent = 2 digits for currency=EUR)
        exponent:
          type: integer
          format: int32
          description: Exponent of Amount. Number of decimal digits.
        isoCode:
          type: string
          description: 'Currency code of amount

            The currency in ISO4217 alphabetic format.

            Example: EUR for Euro'
      title: Amount
    AccountIdentifier:
      type: object
      properties:
        accountReference:
          type: string
          description: Account reference is to identify the Account calculated by the system (algorithm is configurable per issuer). Either the account number or the issuerAccountExternalReference is provided, or, if both are provided then only the account number is used.
        issuerAccountExternalReference:
          type: string
          description: Issuer account external reference is to identify the Account. Either the account number or the issuerAccountExternalReference is provided, or, if both are provided then only the account number is used. Algorithm configurable by issuer, can be generated by the system if there is an externalReferenceGeneratorAlgorithm.
      title: AccountIdentifier
    ApiResponseEntityCancelDirectDebitResponse:
      x-wl-api-response: true
      type: object
      required:
      - responseMetadata
      properties:
        responseMetadata:
          description: Response metadata
          allOf:
          - $ref: '#/components/schemas/ResponseMetadata'
        data:
          description: Response data
          allOf:
          - $ref: '#/components/schemas/CancelDirectDebitResponse'
      description: Issuer response entity
      title: ApiResponseEntityCancelDirectDebitResponse
    CancelDirectDebitResponse:
      type: object
      required:
      - directDebitIdentifier
      - status
      - cancellationDate
      properties:
        directDebitIdentifier:
          description: Direct debit identifier
          allOf:
          - $ref: '#/components/schemas/DirectDebitIdentifier'
        status:
          type: string
          description: Direct debit status
        cancellationDate:
          type: string
          format: date-time
          description: The date when the Direct Debit order was canceled
      title: CancelDirectDebitResponse
    ResponseMetadata:
      type: object
      required:
      - correlationId
      - responseDateTime
      - statusCode
      - statusMessage
      properties:
        correlationId:
          type: string
          description: Correlation Identifier
        links:
          description: Metadata Links
          allOf:
          - $ref: '#/components/schemas/Links'
        statusMessage:
          type: string
          example: Executed successfully
          description: Executed REST API status message
        statusCode:
          type: integer
          format: int32
          example: 200
          description: HTTP status code
        responseDateTime:
          type: string
          example: format:yyyy-MM-dd'T'HH:mm:ss.SSSZ
          description: Timestamp when response date was generated
        timeTakenMs:
          type: integer
          format: int64
          example: 12
          description: Wall clock time required from service to generate the response
      title: ResponseMetadata
    ForbiddenResponseMetadata:
      type: object
      required:
      - correlationId
      - responseDateTime
      - statusCode
      - statusMessage
      properties:
        correlationId:
          type: string
          description: Correlation Identifier
        responseDateTime:
          type: string
          example: format:yyyy-MM-dd'T'HH:mm:ss.SSSZ
          description: Timestamp when response date was generated
        statusCode:
          type: integer
          format: int32
          example: 403
          description: HTTP status code
        statusMessage:
          type: string
          example: Forbidden
          description: Executed REST API status message
      title: ForbiddenResponseMetadata
    CreateDirectDebitResponse:
      type: object
      required:
      - directDebitIdentifier
      - status
      properties:
        directDebitIdentifier:
          description: Direct debit identifier
          allOf:
          - $ref: '#/components/schemas/DirectDebitIdentifier'
        status:
          type: string
          description: Direct debit status
      title: CreateDirectDebitResponse
    InternalServerErrorErrorApiResponse:
      type: object
      required:
      - responseMetadata
      properties:
        responseMetadata:
          allOf:
          - $ref: '#/components/schemas/InternalServerErrorResponseMetadata'
      title: InternalServerErrorErrorApiResponse
    CreateDirectDebitRequest:
      type: object
      required:
      - overPaymentAccountIdentifier
      - amount
      properties:
        overPaymentAccountIdentifier:
          description: Card account identifier to be credited
          allOf:
          - $ref: '#/components/schemas/AccountIdentifier'
        amount:
          description: Amount of Direct Debit
          allOf:
          - $ref: '#/components/schemas/Amount'
        externalOperationCode:
          type: string
          description: The external operation code of the balance adjustment can be provided.
        paymentReason:
          type: string
          description: 'The reason why the payment is triggerred

            The list of possible payment reasons is configurable per issuer.'
      title: CreateDirectDebitRequest
    ApiResponseEntityDirectDebit:
      x-wl-api-response: true
      type: object
      required:
      - responseMetadata
      properties:
        responseMetadata:
          description: Response metadata
          allOf:
          - $ref: '#/components/schemas/ResponseMetadata'
        data:
          description: Response data
          allOf:
          - $ref: '#/components/schemas/DirectDebit'
      description: Issuer response entity
      title: ApiResponseEntityDirectDebit
  securitySchemes:
    basic:
      type: oauth2
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/token