openapi: '3.0.1'
info:
  version: July 31, 2026
  title: Treezor API
  description: |
    As a REST API, Treezor accepts and returns JSON payloads, along with the associated `application/json` content type.

    You can learn everything you need to know about authentication, credentials, data formats, and more in the [API Basics](/guide/api-basics/environments.html) section.
    
    Like the rest of the documentation, this reference focuses on the latest version of the Treezor API (Connect).
  contact:
    name: Treezor
    url: https://treezor.com
  license:
    name: Proprietary
    url: https://treezor.com
servers:
  - url: https://baseURL.co
    # description: Dummy URL for content optimization in API Reference
  - url: https://your-company-name.sandbox.treezor.co
    description: Sandbox environment
  - url: https://your-company-name.api.treezor.com
    description: Production environment
paths:
  /core-connect/account-details/{walletId}/raw:
    get:
      tags:
        - Account Documents
      summary: Get JSON Account Details
      description: | 
        Retrieve the necessary data (JSON) to generate the Account Details of a given Wallet.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
        
      operationId: getRawWalletAccountDetail
      parameters:
        # - $ref: '#/components/parameters/Authorization'
        - name: walletId
          in: path
          description: The unique identifier of the Wallet.
          required: true
          schema:
            type: string
            example: "12345"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: The account details object.
                properties:
                  bic:
                    type: string
                    description: |
                      The [BIC](/guide/overview/glossary.html#bank-identifier-code-bic) of the account.
                    example: "TRZOFR21XXX"
                  iban:
                    type: string
                    description: |
                      The [IBAN](/guide/wallets/iban.html) of the account.
                    example: "FR7630006000011234567890189"
                  title:
                    type: string
                    description: |
                      The title of the user who owns the account.
                    example: "MX"
                    enum:
                     - M
                     - MLLE
                     - MME
                     - MX
                  firstname:
                    type: string
                    description: |
                      The first name of the user who owns the account.
                    example: "Alex"
                  lastname:
                    type: string
                    description: |
                      The last name of the user who owns the account.
                    example: "Oak"
                  postcode:
                    type: string
                    description: |
                      The postal code of the address of the user who owns the account.
                    example: "75000"
                  city:
                    type: string
                    description: |
                      The city of the address of the user who owns the account.
                    example: "Paris"
                  address1:
                    type: string
                    description: |
                      The address of the user who owns the account.
                    example: "15 Treewoods lane"
                  address2:
                    type: string
                    description: |
                      The second line of the address of the user who owns the account.
                  countryName:
                    type: string
                    description: |
                      The country of the address of the user who owns the account.
                    example: "France"
                  treezorAddress:
                    type: object
                    properties:
                      name:
                        type: string
                        example: "Treezor SAS"
                      address1: 
                        type: string
                        example: "33, av de Wagram"
                      address2:
                        type: string
                        nullable: true
                      postcode:
                        type: string
                        example: "75017"
                      city:
                        type: string
                        example: Paris
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - read_only
            - read_write
  /core-connect/account-details/{walletId}/computed:
    get:
      tags:
        - Account Documents
      summary: Get PDF Account Details
      description: | 
        Retrieve a Wallet account details in PDF format.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |

      operationId: getComputedWalletAccountDetail
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: walletId
          in: path
          description: The unique identifier of the Wallet.
          required: true
          schema:
            type: string
            example: "12345"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: The PDF account details to download.
                properties:
                  link:
                    type: string
                    description: The URL to download the PDF file.
                    example: https://xxx.s3.eu-west-3.amazonaws.com/tmp/xxx.pdf
                  expireIn:
                    type: integer
                    description: The time after which the download link expires (in seconds).
                    example: 300
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write

  /core-connect/certificates/walletClosure/{walletId}/raw:
    get:
      summary: Get JSON Closure Certificate
      description: |
        Retrieve a Wallet closure certificate in raw format.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getWalletClosureRaw
      tags: 
        - Account Documents
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: walletId
          in: path
          required: true
          description: The unique identifier of the wallet.
          schema:
            type: integer
            format: int64
            example: 1010544
      security:
        - OAuth2:
            - read_write
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClosureRawResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /core-connect/certificates/walletBalance/{walletId}/raw:
    get:
      summary: Get JSON Balance Certificate
      description: |
        Retrieve a Wallet balance certificate in raw format.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getWalletBalanceRaw
      tags: 
        - Account Documents
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: walletId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: The unique identifier of the wallet.
          example: 1010544
      security:
        - OAuth2:
            - read_write
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceRawResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /core-connect/certificates/walletDomiciliation/{walletId}/raw:
    get:
      summary: Get JSON Domiciliation Certificate
      description: |
        Retrieve a Wallet domiciliation certificate in raw format.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getWalletDomiciliationRaw
      tags:
        - Account Documents
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: walletId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: The unique identifier of the wallet.
          example: 1010544
      security:
        - OAuth2:
            - read_write
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationRawResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'


  /core-connect/certificates/walletBalance/{walletId}/computed:
    get:
      summary: Get PDF Balance Certificate
      description: |
        Retrieve a Wallet balance certificate in PDF format.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getWalletBalanceComputed
      tags:
        - Account Documents
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: walletId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: The unique identifier of the wallet.
          example: 1010544
      security:
        - OAuth2:
            - read_write
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputedCertificateResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /core-connect/certificates/walletClosure/{walletId}/computed:
    get:
      summary: Get PDF Closure Certificate
      description: |
        Retrieve a Wallet closure certificate in PDF format.
        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getWalletClosureComputed
      tags: 
        - Account Documents
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: walletId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: The unique identifier of the wallet.
          example: 1010544
      security:
        - OAuth2:
            - read_write
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputedCertificateResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /core-connect/certificates/walletDomiciliation/{walletId}/computed:
    get:
      summary: Get PDF Domiciliation Certificate
      description: |
        Retrieve a Wallet domiciliation certificate in PDF format.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getWalletDomiciliationComputed
      tags: 
        - Account Documents
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: walletId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: The unique identifier of the wallet.
          example: 1010544
      security:
        - OAuth2:
            - read_write
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputedCertificateResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  
  /core-connect/certificates/confirmationLetter/{walletId}/raw:
    get:
      summary: Get JSON Confirmation Letter
      description: |
        Retrieve a Legal entity's Wallet confirmation letter in JSON format.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getConfirmationLetterRaw
      tags:
        - Account Documents
      security:
        - OAuth2:
            - read_only
            - read_write
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: walletId
          in: path
          description: The unique identifier of the Wallet.
          required: true
          schema:
            type: integer
            example: 28344233
        - name: date
          in: query
          required: true
          description: |
            The reference date for the confirmation letter.
            
            Must be a past date. Format: `YYYY-MM-DD`
          schema:
            type: string
            format: date
            example: "2025-10-11"
        - name: userId
          in: query
          description: |
            The unique identifier of the legal representative to select.
            
            If not provided, the first legal representative from the list will be used.
          schema:
            type: integer
            example: 102859442
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  legalEntity:
                    type: object
                    description: Information about the legal entity.
                    properties:
                      userId:
                        type: string
                        description: The unique identifier of the legal entity user.
                        example: "102859440"
                      userTypeId:
                        type: integer
                        description: |
                          The type of user.
                          
                          - `2`: Legal entity
                          - `3`: Association
                          - `4`: Organization
                        enum: [2, 3, 4]
                        example: 2
                      legalName:
                        type: string
                        description: The legal name of the entity.
                        example: "Tree Company"
                      legalRegistrationNumber:
                        type: string
                        description: The legal registration number (SIREN/SIRET).
                        example: "79801583000010"
                      legalRegistrationDate:
                        type: string
                        format: date
                        description: The date of legal registration.
                        example: "2013-10-21"
                  usersLR:
                    type: array
                    description: List of legal representatives.
                    items:
                      type: object
                      properties:
                        userId:
                          type: string
                          description: The unique identifier of the legal representative.
                          example: "102859442"
                        userTypeId:
                          type: string
                          description: The type of user (always "1" for individuals).
                          example: "1"
                        userStatus:
                          type: string
                          description: The status of the user.
                          enum: [PENDING, CANCELED, VALIDATED]
                          example: "VALIDATED"
                        title:
                          type: string
                          description: The title of the legal representative.
                          enum: [M, MME, MLLE, MX]
                          example: "MX"
                        firstname:
                          type: string
                          description: The first name of the legal representative.
                          example: "Alex"
                        lastname:
                          type: string
                          description: The last name of the legal representative.
                          example: "Oak"
                        birthday:
                          type: string
                          format: date
                          description: The date of birth.
                          example: "1988-01-12"
                        email:
                          type: string
                          format: email
                          description: The email address.
                          example: "user@example.com"
                        address1:
                          type: string
                          description: The primary address line.
                          example: "11 rue d'Athènes"
                        address2:
                          type: string
                          description: The secondary address line.
                          example: ""
                        postcode:
                          type: string
                          description: The postal code.
                          example: "75009"
                        city:
                          type: string
                          description: The city.
                          example: "Paris"
                        country:
                          type: string
                          format: ISO 3166-1 alpha-2
                          description: The country code (ISO 3166-1 alpha-2).
                          example: "FR"
                        phone:
                          type: string
                          description: The phone number.
                          example: "+33731309131"
                        nationality:
                          type: string
                          description: The nationality code (ISO 3166-1 alpha-2).
                          example: "FR"
                        placeOfBirth:
                          type: string
                          description: The place of birth.
                          example: "Le Blanc-Mesnil"
                        birthCountry:
                          type: string
                          format: ISO 3166-1 alpha-2
                          description: The birth country code (ISO 3166-1 alpha-2).
                          example: "FR"
                        effectiveBeneficiary:
                          type: string
                          description: The percentage of effective beneficiary ownership.
                          example: "33.33"
                  wallet:
                    type: object
                    description: Information about the wallet.
                    properties:
                      walletId:
                        type: string
                        description: The unique identifier of the Wallet.
                        example: "28344233"
                      walletTypeId:
                        type: integer
                        description: |
                          The type of wallet.
                          
                          - `9`: Electronic Wallet
                          - `10`: Payment Account Wallet
                        enum: [9, 10]
                      walletStatus:
                        type: string
                        description: The status of the wallet (must be VALIDATED).
                        enum: [PENDING, CANCELED, VALIDATED]
                        example: "VALIDATED"
                      walletTag:
                        type: string
                      userId:
                        type: string
                      userLastname:
                        type: string
                        description: The last name of the wallet owner.
                      userFirstname:
                        type: string
                        description: The first name of the wallet owner.
                      eventName:
                        type: string
                        description: The name of the wallet.
                        example: "My wallet"
                      bic:
                        type: string
                        description: The BIC (Bank Identifier Code).
                        example: "TRZOFR21XXX"
                      iban:
                        type: string
                        description: The IBAN (International Bank Account Number).
                        example: "FRxx xxxxx xxxxx xxx91557705 xx"
                      currency:
                        type: string
                        description: The currency code (ISO 4217).
                        example: "EUR"
                      country:
                        type: string
                        format: ISO 3166-1 alpha-2
                        description: The country code (ISO 3166-1 alpha-2).
                        example: "FR"
                  balance:
                    type: object
                    description: Balance information at the reference date.
                    properties:
                      balance:
                        type: number
                        format: float
                        description: The balance amount.
                        example: 123.45
                      calculationDate:
                        type: string
                        format: date-time
                        description: |
                          The date and time of balance calculation.
                          
                          Format: `YYYY-MM-DDTHH:mm:ssZ`
                        example: "2025-10-11T00:00:00+00:00"
                  certificateDate:
                    type: string
                    format: date-time
                    description: |
                      The date and time at which the certificate was generated.
                      
                      Format: `YYYY-MM-DDTHH:mm:ssZ`
                    example: "2025-12-02T09:30:23+00:00"
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /core-connect/certificates/confirmationLetter/{walletId}/computed:
    get:
      summary: Get PDF Confirmation Letter
      description: |
        Generate a Legal entity's Wallet confirmation letter in PDF format. The generated PDF link expires after 5 minutes.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getConfirmationLetterComputed
      tags:
        - Account Documents
      security:
        - OAuth2:
            - read_only
            - read_write
      parameters:
       #- $ref: '#/components/parameters/Authorization'
        - name: walletId
          in: path
          description: The unique identifier of the Wallet.
          required: true
          schema:
            type: integer
            example: 28344233
        - name: date
          in: query
          required: true
          description: |
            The reference date for the confirmation letter.
            
            Must be a past date. Format: `YYYY-MM-DD`
          schema:
            type: string
            format: date
            example: "2025-10-11"
        - name: userId
          in: query
          description: |
            The unique identifier of the legal representative to select.
            
            If not provided, the first legal representative from the list will be used.
          schema:
            type: integer
            example: 102859442
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  link:
                    type: string
                    format: uri
                    description: Pre-signed S3 URL to download the PDF certificate.
                    example: "https://s3.amazonaws.com/bucket/confirmationLetter_28344233_20251202.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=..."
                  expireIn:
                    type: integer
                    description: The number of seconds until the link expires.
                    example: 300
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /core-connect/statements/{walletId}/camt53:
    get:
      summary: Get CAMT.053 statement
      description: |
        Retrieve a CAMT.053 format bank statement for a specified wallet and date.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getCamt53Statement
      tags:
        - Account Documents
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: walletId
          in: path
          required: true
          description: The unique identifier of the Wallet.
          schema:
            type: string
        - name: dateFrom
          in: query
          required: true
          description: |
            The start date in `YYYY-MM-DD` format.
          schema:
            type: string
            format: date
            # pattern: '^\d{4}-\d{2}-\d{2}$'
          example: "2026-01-15"
        - name: dateTo
          in: query
          required: true
          description: |
            The end date in `YYYY-MM-DD` format, which must be exactly one day after `dateFrom`.
          schema:
            type: string
            format: date
            #pattern: '^\d{4}-\d{2}-\d{2}$'
          example: "2026-01-16"
      security:
        - OAuth2:
            - read_only
      responses:
        '200':
          description: |
            CAMT.053 (ISO 20022) XML bank statement.
            The response is returned as a gzipped binary stream. Standard HTTP clients with `Accept-Encoding: gzip` will handle decompression automatically.
          headers:
            Content-Encoding:
              description: Indicates the response body is gzip-compressed
              schema:
                type: string
                enum:
                  - gzip
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Camt053Document'
              example: |
                <?xml version="1.0" encoding="UTF-8"?>
                <Document xmlns="urn:iso:std:iso:20022:tech:xsd:camt.053.001.12">
                  <BkToCstmrStmt>
                    <GrpHdr>
                      <MsgId>MSG-20240115-123456</MsgId>
                      <CreDtTm>2024-01-16T00:00:00Z</CreDtTm>
                    </GrpHdr>
                    <Stmt>
                      <Id>STMT-20240115-123456</Id>
                      <CreDtTm>2024-01-16T00:00:00Z</CreDtTm>
                      <FrToDt>
                        <FrDtTm>2024-01-15T00:00:00Z</FrDtTm>
                        <ToDtTm>2024-01-16T00:00:00Z</ToDtTm>
                      </FrToDt>
                      <Acct>
                        <Id><IBAN>FR7600000000000000000000000</IBAN></Id>
                        <Ccy>EUR</Ccy>
                      </Acct>
                      <Bal>
                        <Tp><CdOrPrtry><Cd>OPBD</Cd></CdOrPrtry></Tp>
                        <Amt Ccy="EUR">1000.00</Amt>
                        <CdtDbtInd>CRDT</CdtDbtInd>
                        <Dt><DtTm>2024-01-15T00:00:00Z</DtTm></Dt>
                      </Bal>
                      <Ntry>
                        <NtryRef>TXN-000001</NtryRef>
                        <Amt Ccy="EUR">50.00</Amt>
                        <CdtDbtInd>CRDT</CdtDbtInd>
                        <Sts><Cd>BOOK</Cd></Sts>
                        <ValDt><Dt>2024-01-15</Dt></ValDt>
                        <NtryDtls>
                          <TxDtls>
                            <RltdPties>
                              <Dbtr><Pty><Nm>Jane Doe</Nm></Pty></Dbtr>
                              <Cdtr><Pty><Nm>John Smith</Nm></Pty></Cdtr>
                            </RltdPties>
                            <AddtlTxInf>Payment for services</AddtlTxInf>
                          </TxDtls>
                        </NtryDtls>
                      </Ntry>
                    </Stmt>
                  </BkToCstmrStmt>
                </Document>

        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /oauth/token:
    post:
      tags:
        - Authentication
      summary: Obtain Access Token
      operationId: postAuth
      description: |
        Exchange authorization codes or refresh tokens for access tokens.
        The response will include the access token and optionally a refresh token, along with their expiration details.
      security: []
      requestBody:
        content:
          multipart/form-data:
            schema:
              oneOf:
                - type: object
                  properties:
                    grant_type:
                      type: string
                      default: client_credentials
                      description: |
                        MUST BE "client_credentials" value for client credential flow.
                    client_id:
                      type: string
                    client_secret:
                      type: string
                    scope:
                      type: string
                      description: space separated
                - type: object
                  properties:
                    grant_type:
                      type: string
                      default: password
                      description: MUST BE "password" value for password credential flow
                    client_id:
                      type: string
                    client_secret:
                      type: string
                    scope:
                      type: string
                      description: space separated
                    username:
                      type: string
                    password:
                      type: string
                      description: User password
                - type: object
                  properties:
                    grant_type:
                      type: string
                      default: refresh_token
                      description: MUST BE "refresh_token" value for refresh token flow
                    client_id:
                      type: string
                    client_secret:
                      type: string
                    scope:
                      type: string
                      description: space separated
                    refresh_token:
                      type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                oneOf:
                  - type: object
                    properties:
                      token_type:
                        type: string
                        default: Bearer
                        description: |
                          This value must be passed in the "Authorization" header of your API requests as follows: "Authorization: Bearer <token>" (with a space between "Bearer" and the token value).
                      expires_in:
                        type: integer
                        default: 3600
                      access_token:
                        type: string
                        description: JWT token
                  - type: object
                    properties:
                      token_type:
                        type: string
                        default: Bearer
                        description: |
                          This value must be passed in the "Authorization" header of your API requests as follows: "Authorization: Bearer <token>" (with a space between "Bearer" and the token value).
                      expires_in:
                        type: integer
                        default: 3600
                      access_token:
                        type: string
                        description: JWT token
                      refresh_token:
                        type: string
                        description: |
                          A refresh token to regenerate a JWT token without sending all of information request at the first request on password grant.
                  - type: object
                    properties:
                      token_type:
                        type: string
                        default: Bearer
                        description: |
                          This value must be passed in the "Authorization" header of your API requests as follows: "Authorization: Bearer <token>" (with a space between "Bearer" and the token value).
                      expires_in:
                        type: integer
                        default: 3600
                      access_token:
                        type: string
                        description: JWT token
                      refresh_token:
                        type: string
                        description: |
                          A refresh token to regenerate a JWT token without sending all of information request at the first request on password grant.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /core-connect/balances/{walletId}:
    get:
      tags:
        - Balances
      summary: Get Wallet Balance history
      description: | 
        Retrieve the Balance History of a Wallet.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session with 180 days exemption |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getWalletBalanceHistory
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: walletId
          in: path
          description: The unique identifier of the Wallet.
          required: true
          schema:
            type: integer
            example: 12345
        - name: dateFrom
          in: query
          description: Start date in RFC 3339 full-date format.
          schema:
            type: string
            format: RFC 3339 full-date
            example: "2024-12-01"
        - name: dateTo
          in: query
          description: End date in RFC 3339 full-date format.
          schema:
            type: string
            format: full-date
            example: "2025-02-10"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: object
                  description: | 
                    Balance entries, identified by dates (format: `YYYY-MM-DD HH:mm:ss`).
                  properties:
                    solde:
                      type: number
                      format: float
                      description: |
                        The [current balance](/guide/wallets/balances.html) of the wallet.
                      example: 101.25
                    authorizedBalance:
                      type: number
                      format: float
                      description: |
                        The [authorized balance](/guide/wallets/balances.html) of the wallet.
                      example: 80
                    currency:
                      type: string
                      description: The currency of the Wallet.
                      example: "EUR"
                example:
                  "2025-01-09 11:46:44":
                    solde: 101.25
                    authorizedBalance: 80
                    currency: "EUR"
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - read_only
            - read_write
  /core-connect/cardtransactions:
    get:
      tags:
        - Card Transactions
      summary: Get all Card Transactions (Deprecated)
      operationId: getCoCardTransactions
      deprecated: true
      description: | 
        ⚠️ **This endpoint is deprecated.** Use [`GET /v1/cardtransactions`](/api-reference/api-endpoints.html#tag/Card%20Transactions/readCardTransaction) instead.

        Retrieve all the Card Transactions. This is the preferred request for a dashboard-oriented approach. You shouldn't expose this endpoint to your end users.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: cursor
          in: query
          description: Pagination cursor, if you don't pass a cursor, result will start at the first page.
          schema:
            type: string
            example: "da4b9237bacccdf19c0760cab7aec4a8359010b0"
        - name: pageSize
          in: query
          description: Pagination cursor, if you don't pass a cursor, result will start at the first page.
          schema:
            type: number
            format: integer
            example: 10
            default: 50
        - name: createdDateFrom
          in: query
          description: | 
            The date and time from which the transactions are taken into account in RFC 339 date-time format (HTML encoded).
          schema:
            type: string
            format: RFC 3339 date-time
            example: "2025-01-18T11:00:00%2B01:00"
        - name: createdDateTo
          in: query
          description: | 
            The date and time up to which the transactions are taken into account in RFC 339 date-time format (HTML encoded).
          schema:
            type: string
            format: RFC 3339 date-time
            example: "2025-04-18T11:00:00%2B01:00"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  cardTransactions:
                    type: array
                    items:
                      type: object
                      properties:
                        cardtransactionId:
                          type: string
                          description: The unique identifier of the Card Transaction.
                          example: "12345"
                        cardId:
                          type: string
                          description: The unique identifier of the card used for the transaction.
                          example: "12345"
                        walletId:
                          type: string
                          description: The unique identifier of the Wallet the card is attached to.
                          example: "12345" 
                        acquirerId:
                          type: string
                          description: The identifier of the merchant's bank (acquirer) in the form of 5 to 6 digits.
                          example: "666666"
                        walletCurrency:
                          type: string
                          format: ISO 4217 3-digit code
                          description: The currency of the Wallet the card is attached to.
                          example: "978"
                        merchantId:
                          type: string
                          description: |
                            The [Merchant Identifier Number (MID)](/guide/overview/glossary#merchant-identifier-number-mid).
                        merchantName:
                          type: string
                          description: The name of the merchant.
                        merchantCity:
                          type: string
                          description: The address city of the merchant.
                        merchantCountry:
                          type: string
                          format: ISO 3166
                          description: | 
                            The address country of the merchant. ISO 3166 3-letter code (except of the US which is a two-letter code)
                          example: "FRA"
                        mccCode:
                          type: string
                          description: | 
                            The [Merchant Category Code (MCC)](/guide/overview/glossary#merchant-category-code-mcc). A MCC valued to `6011` indicates a withdrawal.
                            
                            Some MCC are prohibited for [anonymous electronic money](/guide/wallets/introduction#electronic-money-wallet-type-9), such as: money transfer, money order, foreign currency, liquid and cryptocurrency assets, lotteries, on-line gambling, betting, etc.
                          example: "5812"
                        paymentLocalTime:
                          type: string
                          # pattern: '^\d{2}[0-5]\d[0-5]\d$'
                          description: |
                            The local time at which the transaction occurred.

                            Format: `HHmmss` (24-hour format, e.g., `235959` for 23:59:59).
                          example: "235959"
                        publicToken:
                          type: string
                          description: | 
                            The token of the card. This is a way to identify a card without knowing or communicating its [PAN](/guide/overview/glossary#primary-account-number-pan).
                          example: "107688667"
                        paymentAmount:
                          type: string
                          format: float
                          description: | 
                            The amount of the transaction, always expressed in Euros. See the `paymentLocalAmount` for the value in the payment local currency.
                          example: "11.90"
                        paymentCurrency:
                          type: string
                          format: ISO 4217
                          description: |
                            The currency of the payment. Format: [ISO 4217](/guide/api-basics/data-format.html#currencies) 3-digit code.
                          example: "978"
                        fees:
                          type: string
                          description: ATM usage or foreign payments fees as defined by Treezor, always set to `0`.
                          example: "0"
                        paymentCountry:
                          type: string
                          format: ISO 3166
                          description: Country in which the transaction occurred, ISO 3166 3-letter code.
                          example: "FRA"
                        paymentId:
                          type: string
                          description: | 
                            The unique identifier of the card payment (or attempted payment), allowing you to follow the card transaction life cycle.
                        paymentStatus:
                          type: string
                          description: |
                            The status of the payment. See the [Statuses](/guide/cards/transactions.html#statuses-paymentstatus) article for more information.
                          enum: ["A","C","I","M","R","S","V"]
                        paymentLocalAmount:
                          type: string
                          format: float
                          description: The amount of the transaction in the local currency.
                          example: "12.80"
                        posCardholderPresence:
                          type: string
                          description: |
                            Indicates whether the cardholder was physically present, and if not, how they ordered the card transaction.
                            
                            See [Cardholder Presence](/guide/cards/transactions.html#cardholder-presence-poscardholderpresence) for more information.
                          enum: ["0","1","2","3","4","5","6","9"]
                        posPostcode:
                          type: string
                          description: Postcode of the point of sale where the transaction occurred.
                        posCountry:
                          type: string
                          format: ISO 3166
                          description: Country of the point of sale where the transaction occurred, in ISO 3166 3-digit code format.
                          example: "250"
                        posTerminalId:
                          type: string
                          description: The identifier of the terminal used for the transaction.
                          example: "B1234567"
                          minLength: 1
                          maxLength: 8
                        posCardPresence:
                          type: string
                          description: |
                            Indicates whether the card was physically present during the transaction: 
                            * `0` – The card was present.
                            * `1` – The card was absent.
                            * `9` – The card presence cannot be determined.
                          enum: ["0","1","9"]
                        panEntryMethod:
                          type: string
                          description: |
                            Indicates how the merchant captured the [PAN](/guide/overview/glossary.html#primary-account-number-pan). See [PAN Entry Method](/guide/cards/transactions.html#pan-entry-method-panentrymethod) for more information.
                          enum: ["0","1","2","3","4","5","7","10","79","80","81","91"]
                        authorizationNote:
                          type: string
                          description: |
                            Information regarding the cause of a payment incident and/or status. 
                            
                            See [Authorization Notes](/guide/cards/authorization-notes.html) for more information and a list of common examples.
                          maxLength: 256
                          example: "DR: Card not found UnKnownCard"
                        authorizationResponseCode:
                          type: string
                          description: |
                            Response code for a given card transaction, providing additional information regarding as to why a transaction was accepted or refused.

                            See [Authorization Codes](/guide/cards/authorization-notes.html#authorization-response-codes) for more information.
                          example: "10"
                        authorizationIssuerId:
                          type: string
                          description: The transaction identifier as generated by the payment processor.
                        authorizationIssuerTime:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: | 
                            The date and time at which the payment processor authorized the transaction. This value is based on the processor's timezone (Europe/London).

                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2025-02-12 13:00:00"
                        authorizationMti:
                          type: string
                          description: |
                            Authorization Message Type Identifier. Please rely on the `paymentStatus` value.
                          example: "100"
                        authorizedBalance:
                          type: string
                          format: float
                          description: | 
                            The [Authorized Balance](/guide/wallets/balances.html) of the wallet after the transaction.
                          example: "345.88"
                        limitAtmYear:
                          type: string
                          description: | 
                            The ATM operations limit of the corresponding card for a sliding year.

                            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                          example: "0"
                        limitAtmMonth:
                          type: string
                          description: | 
                            ATM operations limit of the corresponding card for a sliding month.

                            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                          example: "0"
                        limitAtmWeek:
                          type: string
                          description: | 
                            ATM operations limit of the corresponding card for a sliding week.

                            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                          example: "2000"
                        limitAtmDay:
                          type: string
                          description: | 
                            ATM operations limit of the corresponding card for a single day.

                            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                          example: "1000"
                        limitAtmAll:
                          type: string
                          description: | 
                            ATM operations limit of the corresponding card from beginning.

                            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                          example: "0"
                        limitPaymentYear:
                          type: string
                          description: |
                            POS operations limit of the corresponding card for a sliding year.

                            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                          example: "0"
                        limitPaymentMonth:
                          type: string
                          description: | 
                            POS operations limit of the corresponding card for a sliding month.

                            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                          example: "0"
                        limitPaymentWeek:
                          type: string
                          description: | 
                            POS operations limit of the corresponding card for a sliding week.

                            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                          example: "3000"
                        limitPaymentDay:
                          type: string
                          description: | 
                            POS operations limit of the corresponding card for a single day.

                            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                          example: "2000"
                        limitPaymentAll:
                          type: string
                          description: | 
                            POS operations limit of the corresponding card from beginning.

                            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                          example: "0"
                        totalLimitAtmYear:
                          type: string
                          format: float
                          description: The card yearly withdrawal amount.
                          example: "0.00"
                        totalLimitAtmMonth:
                          type: string
                          description: The card monthly withdrawal amount.
                          format: float
                          example: "0.00"
                        totalLimitAtmWeek:
                          type: string
                          description: The card weekly withdrawal amount.
                          format: float
                          example: "0.00"
                        totalLimitAtmDay:
                          type: string
                          format: float
                          description: The card daily withdrawal amount.
                          example: "0.00"
                        totalLimitAtmAll:
                          type: string
                          format: float
                          description: The card total withdrawal amount.
                          example: "0.00"
                        totalLimitPaymentYear:
                          type: string
                          format: float
                          description: The card yearly spent amount.
                          example: "0.00"
                        totalLimitPaymentMonth:
                          type: string
                          format: float
                          description: The card monthly spent amount.
                          example: "0.00"
                        totalLimitPaymentWeek:
                          type: string
                          format: float
                          description: The card weekly spent amount.
                          example: "0.00"
                        totalLimitPaymentDay:
                          type: string
                          format: float
                          description: The card daily spent amount.
                          example: "0.00"
                        totalLimitPaymentAll:
                          type: string
                          format: float
                          description: The card total spent amount.
                          example: "0.00"
                        paymentDailyLimit:
                          type: string
                          nullable: true
                          format: float
                          description: The daily payment limit.
                          example: "0.00"
                        cardDigitalizationExternalId:
                          type: string
                          nullable: true
                          description: |
                            The digital payment token identifier (only present if payment was made with a digital token such as Apple Pay or Google Pay for example).
                        is3DS:
                          type: string
                          nullable: true
                          description: |
                            Indicates whether [3DSecure](/guide/overview/glossary#_3ds-3d-secure) was used for authentication:
                            * `0` – 3DS was not used
                            * `1` – 3DS was used
                          enum: ["0","1"]
                        merchantAddress:
                          type: string
                          description: The address of the merchant.
                          nullable: true
                        paymentLocalDate:
                          type: string
                          description: | 
                            The local date on which the transaction occurred.

                            Format: `YYYYMMDD` (e.g., `20251228` for December 28, 2025)
                          example: "20251228"
                          nullable: true
                        optimizedMerchantName:
                          type: string
                          maxLength: 50
                          description: The name of the merchant, optimized for display and understanding.
                          example: "Merchant's Name"
                          nullable: true
                        merchantLogo:
                          type: string
                          format: uri
                          description: The URL's of the merchant's logo.
                          example: "https://storage.googleapis.com/merchantlogo.png"
                          nullable: true
                        merchantCategory:
                          type: string
                          description: The category of the merchant. Value may be displayed in the cardholder's language if available.
                          example: "Retail & Shopping"
                          nullable: true
                          enum:
                            - "Bills, Fees & Services"
                            - "Cash & Banking"
                            - "Charity & Donations"
                            - "Cultural & Education"
                            - "Eating Out"
                            - "Entertainment & Recreation"
                            - "Groceries & Supermarkets"
                            - "Health & Wellness"
                            - "Home & Family"
                            - "Other"
                            - "Retail & Shopping"
                            - "Transportation & Mobility"
                            - "Travel & Holidays"
                        merchantCategoryGroup:
                          type: string
                          description: | 
                            Sub-group of the category defined in `merchantCategory`. Value may be displayed in the cardholder's language if available.
                          nullable: true
                          example: "Retail & Department Stores"
                        merchantCategoryType:
                          type: string
                          description: |
                            Precise type of the sub-group defined in `merchantCategoryGroup`. Value may be displayed in the cardholder's language if available.
                          nullable: true
                          example: "Furniture"
                        transactionSubtype:
                          type: string
                          description: |
                            Additional information regarding the type of card transaction. Values can be:
                              * `OFT` – Offline transaction
                              * `PRE` – Preauthorization
                              * `SEP` – Second presentment
                          enum:
                            - OFT
                            - PRE
                            - SEP
                        3dsExemptionType:
                          type: string
                          deprecated: true
                          description: | 
                            Deprecated. See `exemptionType3ds`.
                          example: "2"
                        exemptionType3ds:
                          type: string
                          description: | 
                            Indicates why the transaction was exempted for 3DS authentication. See [3DS Exemption Type](/guide/cards/transactions.html#_3ds-exemption-type-exemptiontype3ds) for the value list.
                          example: "2"
                        receiverData:
                          type: string
                          description: | 
                            For MoneySend transactions, information regarding the receiver. It usually includes details such as the receiver's name, masked pan, and address, separated by digits.
                          example: "0104Alex0303Oak0411Main Street0510Willow Lane0703USA"
                        senderData:
                          type: string
                          description: | 
                            For MoneySend transactions, information regarding the sender. It usually includes details such as the sender's name, masked pan, and address, separated by digits.
                          example: "0104Alex0303Oak0411Main Street0510Willow Lane0703USA"
                        transactionTypeIdentifier:
                          type: string
                          description: | 
                            For MoneySend transactions, code indicating the type of transaction and the source of funds. Can be:
                              * `C07` – Person-to-Person Transfer
                              * `C52` – General Transfer to Own Account
                              * `C53` – Agent Cash Out
                              * `C54` – Payment of Own Credit Card Bill
                              * `C55` – Business Disbursement
                              * `C56` – Government/Non-profit Disbursement
                              * `C57` – Rapid Merchant Settlement
                              * `C59` – Cash-in at Point of Sale
                              * `C65` – General Business-to-Business Transfer
                          enum: ["C07","C52","C53","C54","C55","C56","C57","C59","C65"]
                        localMerchantId:
                          type: string
                          description: Indicates the merchant's SIREN or SIRET if available.
                        userId:
                          type: integer
                          description: The unique identifier of the User who owns the Wallet the card is attached to.
                        authorizationIdResponse:
                          type: string
                          description: A unique identifier generated by the issuing institution during a transaction. 
                          example: "560268"
                          nullable: true
                        isPinValidated:
                          type: boolean
                          description: Whether the PIN was entered and successfully verified.
                          nullable: true
                  cursor:
                    type: object
                    properties:
                      prev:
                        type: string
                        nullable: true
                        description: |
                          Pointer value for previous page. Set to `null` when on the first page.
                        example: "356a192b7913b04c54574d18c28d46e6395428ab"
                      current:
                        type: string
                        nullable: true
                        description: |
                          Pointer for the current page.
                        example: "da4b9237bacccdf19c0760cab7aec4a8359010b0"
                      next:
                        type: string
                        nullable: true
                        description: |
                          Pointer value for next page. Set to `null` when on the first page.
                        example: "da4b9237bacccdf19c0760cab7aec4a8359010b0"
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - admin
  /core-connect/cardtransactions/{cardId}:
    get:
      tags:
        - Card Transactions
      summary: Get Card Transactions (Deprecated)
      operationId: getCoCardTransaction
      deprecated: true
      description: | 
        ⚠️ **This endpoint is deprecated.** Use [`GET /v1/cardtransactions`](/api-reference/api-endpoints.html#tag/Card%20Transactions/readCardTransaction) instead.

        Retrieve the Card Transactions for a specific card. This request is preferred for a dashboard-oriented usage. You shouldn't expose this endpoint to your end users.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: path
          required: true
          description: The unique identifier of the card.
          schema:
            type: string
            example: "12345"
        - name: cursor
          in: query
          description: Pagination cursor, if you don't pass a cursor, result will start at the first page.
          schema:
            type: string
            example: "da4b9237bacccdf19c0760cab7aec4a8359010b0"
        - name: pageSize
          in: query
          description: Pagination cursor, if you don't pass a cursor, result will start at the first page.
          schema:
            type: number
            format: integer
            example: 10
            default: 50
        - name: createdDateFrom
          in: query
          description: The date and time from which the transactions are taken into account in RFC 3339 date-time format (HTML encoded).
          schema:
            type: string
            format: RFC 3339 date-time
            example: "2025-04-18T11:00:00%2B01:00"
        - name: createdDateTo
          in: query
          description: The date and time up to which the transactions are taken into account in RFC 3339 date-time format (HTML encoded).
          schema:
            type: string
            format: RFC 3339 date-time
            example: "2025-04-18T11:00:00%2B01:00"
        - name: amountFrom
          in: query
          description: The minimum amount of the transactions to be taken into account.
          schema:
            type: number
            format: float
            example: 10.25
        - name: amountTo
          in: query
          description: The maximum amount of the transactions to be taken into account.
          schema:
            type: number
            format: float
            example: 100.25
        - name: paymentStatus
          in: query
          schema:
            type: array
            items:
              type: string
              enum: ["A","C","I","M","R","S","V"]
        - name: paymentType
          in: query
          schema:
            type: array
            items:
              type: string
              enum:
                - Payment
                - Withdrawal
        - name: merchantId
          in: query
          description: | 
            The unique identifier of the merchant. See [Merchant Identification Number (MID)](/guide/overview/glossary.html#merchant-identification-number-mid).
          schema:
            type: string
        - name: walletId
          in: query
          description: The unique identifier of the wallet to search for.
          schema:
            type: string
            example: "12345"
        - name: paymentId
          in: query
          description: The payment unique identifier to search for.
          schema:
            type: string
            example: "12345"
        - name: mcc
          in: query
          description: Filter on the mccCode attribute.
          schema:
            type: string
            example: "5814"
        - name: is3DS
          in: query
          description: Filter on the is3DS attribute.
          schema:
            type: string
            example: "0"
        - name: xpay
          in: query
          description: Filter on the cardDigitalizationExternalId attribute.
          schema:
            type: string
            example: "123456789"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  cardTransactions:
                    type: array
                    items:
                      type: object
                      properties:
                        cardtransactionId:
                          type: string
                          description: The unique identifier of the Card Transaction.
                          example: "12345"
                        cardId:
                          type: string
                          description: The unique identifier of the card used for the transaction.
                          example: "12345"
                        walletId:
                          type: string
                          description: The unique identifier of the Wallet the card is attached to.
                          example: "12345" 
                        acquirerId:
                          type: string
                          description: The identifier of the merchant's bank (acquirer) in the form of 5 to 6 digits.
                          example: "666666"
                        walletCurrency:
                          type: string
                          format: ISO 4217 3-digit code
                          description: The currency of the Wallet the card is attached to.
                          example: "978"
                        merchantId:
                          type: string
                          description: |
                            The [Merchant Identifier Number (MID)](/guide/overview/glossary#merchant-identifier-number-mid).
                        merchantName:
                          type: string
                          description: The name of the merchant.
                        merchantCity:
                          type: string
                          description: The address city of the merchant.
                        merchantCountry:
                          type: string
                          format: ISO 3166
                          description: | 
                            The address country of the merchant. ISO 3166 3-letter code (except of the US which is a two-letter code)
                          example: "FRA"
                        mccCode:
                          type: string
                          description: | 
                            The [Merchant Category Code (MCC)](/guide/overview/glossary#merchant-category-code-mcc). A MCC valued to `6011` indicates a withdrawal.
                            
                            Some MCC are prohibited for [anonymous electronic money](/guide/wallets/introduction#electronic-money-wallet-type-9), such as: money transfer, money order, foreign currency, liquid and cryptocurrency assets, lotteries, on-line gambling, betting, etc.
                          example: "5812"
                        paymentLocalTime:
                          type: string
                          # pattern: '^\d{2}[0-5]\d[0-5]\d$'
                          description: |
                            The local time at which the transaction occurred.

                            Format: `HHmmss` (24-hour format, e.g., `235959` for 23:59:59).
                          example: "235959"
                        publicToken:
                          type: string
                          description: | 
                            The token of the card. This is a way to identify a card without knowing or communicating its [PAN](/guide/overview/glossary#primary-account-number-pan).
                          example: "107688667"
                        paymentAmount:
                          type: string
                          format: float
                          description: | 
                            The amount of the transaction, always expressed in Euros. See the `paymentLocalAmount` for the value in the payment local currency.
                          example: "11.90"
                        paymentCurrency:
                          type: string
                          format: ISO 4217
                          description: |
                            The currency of the payment. Format: [ISO 4217](/guide/api-basics/data-format.html#currencies) 3-digit code.
                          example: "978"
                        fees:
                          type: string
                          description: ATM usage or foreign payments fees as defined by Treezor, always set to `0`.
                          example: "0"
                        paymentCountry:
                          type: string
                          format: ISO 3166
                          description: Country in which the transaction occurred, ISO 3166 3-letter code.
                          example: "FRA"
                        paymentId:
                          type: string
                          description: | 
                            The unique identifier of the card payment (or attempted payment), allowing you to follow the card transaction life cycle.
                        paymentStatus:
                          type: string
                          description: |
                            The status of the payment. See the [Statuses](/guide/cards/transactions.html#statuses-paymentstatus) article for more information.
                          enum: ["A","C","I","M","R","S","V"]
                        paymentLocalAmount:
                          type: string
                          format: float
                          description: The amount of the transaction in the local currency.
                          example: "12.80"
                        posCardholderPresence:
                          type: string
                          description: |
                            Indicates whether the cardholder was physically present, and if not, how they ordered the card transaction.
                            
                            See [Cardholder Presence](/guide/cards/transactions.html#cardholder-presence-poscardholderpresence) for more information.
                          enum: ["0","1","2","3","4","5","6","9"]
                        posPostcode:
                          type: string
                          description: Postcode of the point of sale where the transaction occurred.
                        posCountry:
                          type: string
                          format: ISO 3166
                          description: Country of the point of sale where the transaction occurred, in ISO 3166 3-digit code format.
                          example: "250"
                        posTerminalId:
                          type: string
                          description: The identifier of the terminal used for the transaction.
                          example: "B1234567"
                          minLength: 1
                          maxLength: 8
                        posCardPresence:
                          type: string
                          description: |
                            Indicates whether the card was physically present during the transaction: 
                            * `0` – The card was present.
                            * `1` – The card was absent.
                            * `9` – The card presence cannot be determined.
                          enum: ["0","1","9"]
                        panEntryMethod:
                          type: string
                          description: |
                            Indicates how the merchant captured the [PAN](/guide/overview/glossary.html#primary-account-number-pan). See [PAN Entry Method](/guide/cards/transactions.html#pan-entry-method-panentrymethod) for more information.
                          enum: ["0","1","2","3","4","5","7","10","79","80","81","91"]
                        authorizationNote:
                          type: string
                          description: |
                            Information regarding the cause of a payment incident and/or status. 
                            
                            See [Authorization Notes](/guide/cards/authorization-notes.html) for more information and a list of common examples.
                          maxLength: 256
                          example: "DR: Card not found UnKnownCard"
                        authorizationResponseCode:
                          type: string
                          description: |
                            Response code for a given card transaction, providing additional information regarding as to why a transaction was accepted or refused.

                            See [Authorization Codes](/guide/cards/authorization-notes.html#authorization-response-codes) for more information.
                          example: "10"
                        authorizationIssuerId:
                          type: string
                          description: The transaction identifier as generated by the payment processor.
                        authorizationIssuerTime:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: | 
                            The date and time at which the payment processor authorized the transaction. This value is based on the processor's timezone (Europe/London).

                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2025-02-12 13:00:00"
                        authorizationMti:
                          type: string
                          description: |
                            Authorization Message Type Identifier. Please rely on the `paymentStatus` value.
                          example: "100"
                        authorizedBalance:
                          type: string
                          format: float
                          description: | 
                            The [Authorized Balance](/guide/wallets/balances.html) of the wallet after the transaction.
                          example: "345.88"
                        limitAtmYear:
                          type: string
                          description: | 
                            The ATM operations limit of the corresponding card for a sliding year.

                            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) article for more information.
                          example: "0"
                        limitAtmMonth:
                          type: string
                          description: | 
                            ATM operations limit of the corresponding card for a sliding month.

                            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) article for more information.
                          example: "0"
                        limitAtmWeek:
                          type: string
                          description: | 
                            ATM operations limit of the corresponding card for a sliding week.

                            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                          example: "2000"
                        limitAtmDay:
                          type: string
                          description: | 
                            ATM operations limit of the corresponding card for a single day.

                            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                          example: "1000"
                        limitAtmAll:
                          type: string
                          description: | 
                            ATM operations limit of the corresponding card from beginning.

                            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                          example: "0"
                        limitPaymentYear:
                          type: string
                          description: |
                            POS operations limit of the corresponding card for a sliding year.

                            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                          example: "0"
                        limitPaymentMonth:
                          type: string
                          description: | 
                            POS operations limit of the corresponding card for a sliding month.

                            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                          example: "0"
                        limitPaymentWeek:
                          type: string
                          description: | 
                            POS operations limit of the corresponding card for a sliding week.

                            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                          example: "3000"
                        limitPaymentDay:
                          type: string
                          description: | 
                            POS operations limit of the corresponding card for a single day.

                            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                          example: "2000"
                        limitPaymentAll:
                          type: string
                          description: | 
                            POS operations limit of the corresponding card from beginning.

                            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                          example: "0"
                        totalLimitAtmYear:
                          type: string
                          format: float
                          description: The card yearly withdrawal amount.
                          example: "0.00"
                        totalLimitAtmMonth:
                          type: string
                          format: float
                          description: The card monthly withdrawal amount.
                          example: "0.00"
                        totalLimitAtmWeek:
                          type: string
                          format: float
                          description: The card weekly withdrawal amount.
                          example: "0.00"
                        totalLimitAtmDay:
                          type: string
                          format: float
                          description: The card daily withdrawal amount.
                          example: "0.00"
                        totalLimitAtmAll:
                          type: string
                          format: float
                          description: The card total withdrawal amount.
                          example: "0.00"
                        totalLimitPaymentYear:
                          type: string
                          format: float
                          description: The card yearly spent amount.
                          example: "0.00"
                        totalLimitPaymentMonth:
                          type: string
                          format: float
                          description: The card monthly spent amount.
                          example: "0.00"
                        totalLimitPaymentWeek:
                          type: string
                          format: float
                          description: The card weekly spent amount.
                          example: "0.00"
                        totalLimitPaymentDay:
                          type: string
                          format: float
                          description: The card daily spent amount.
                          example: "0.00"
                        totalLimitPaymentAll:
                          type: string
                          format: float
                          description: The card total spent amount.
                          example: "0.00"
                        paymentDailyLimit:
                          type: string
                          nullable: true
                          format: float
                          description: The daily payment limit.
                          example: "0.00"
                        cardDigitalizationExternalId:
                          type: string
                          nullable: true
                          description: |
                            The digital payment token identifier (only present if payment was made with a digital token such as Apple Pay or Google Pay for example).
                        is3DS:
                          type: string
                          nullable: true
                          description: |
                            Indicates whether [3DSecure](/guide/overview/glossary#_3ds-3d-secure) was used for authentication:
                            * `0` – 3DS was not used
                            * `1` – 3DS was used
                          enum: ["0","1"]
                        merchantAddress:
                          type: string
                          nullable: true
                          description: The address of the merchant.
                        paymentLocalDate:
                          type: string
                          nullable: true
                          description: | 
                            The local date on which the transaction occurred.

                            Format: `YYYYMMDD` (e.g., `20251228` for December 28, 2025)
                          example: "20251228"
                        optimizedMerchantName:
                          type: string
                          maxLength: 50
                          description: |
                            The name of the merchant, optimized for display and understanding.
                          example: "Merchant's Name"
                          nullable: true
                        merchantLogo:
                          type: string
                          format: uri
                          description: The URL's of the merchant's logo.
                          example: "https://storage.googleapis.com/merchantlogo.png"
                          nullable: true
                        merchantCategory:
                          type: string
                          description: The category of the merchant. Value may be displayed in the cardholder's language if available.
                          example: "Retail & Shopping"
                          nullable: true
                          enum:
                            - "Bills, Fees & Services"
                            - "Cash & Banking"
                            - "Charity & Donations"
                            - "Cultural & Education"
                            - "Eating Out"
                            - "Entertainment & Recreation"
                            - "Groceries & Supermarkets"
                            - "Health & Wellness"
                            - "Home & Family"
                            - "Other"
                            - "Retail & Shopping"
                            - "Transportation & Mobility"
                            - "Travel & Holidays"
                        merchantCategoryGroup:
                          type: string
                          description: | 
                            Sub-group of the category defined in `merchantCategory`. Value may be displayed in the cardholder's language if available.
                          nullable: true
                          example: "Retail & Department Stores"
                        merchantCategoryType:
                          type: string
                          description: |
                            Precise type of the sub-group defined in `merchantCategoryGroup`. Value may be displayed in the cardholder's language if available.
                          nullable: true
                          example: "Furniture"
                        transactionSubtype:
                          type: string
                          description: |
                            Additional information regarding the type of card transaction. Values can be:
                              * `OFT` – Offline transaction
                              * `PRE` – Preauthorization
                              * `SEP` – Second presentment
                          enum:
                            - OFT
                            - PRE
                            - SEP
                        3dsExemptionType:
                          type: string
                          deprecated: true
                          description: |
                            Deprecated. See `exemptionType3ds`.
                          example: "2"
                        exemptionType3ds:
                          type: string
                          description: | 
                            Indicates why the transaction was exempted for 3DS authentication. See [3DS Exemption Type](/guide/cards/transactions.html#_3ds-exemption-type-exemptiontype3ds) for the value list.
                          example: "2"
                        receiverData:
                          type: string
                          description: | 
                            For MoneySend transactions, information regarding the receiver. It usually includes details such as the receiver's name, masked pan, and address, separated by digits.
                          example: "0104Alex0303Oak0411Main Street0510Willow Lane0703USA"
                        senderData:
                          type: string
                          description: | 
                            For MoneySend transactions, information regarding the sender. It usually includes details such as the sender's name, masked pan, and address, separated by digits.
                          example: "0104Alex0303Oak0411Main Street0510Willow Lane0703USA"
                        transactionTypeIdentifier:
                          type: string
                          description: | 
                            For MoneySend transactions, code indicating the type of transaction and the source of funds. Can be:
                              * `C07` – Person-to-Person Transfer
                              * `C52` – General Transfer to Own Account
                              * `C53` – Agent Cash Out
                              * `C54` – Payment of Own Credit Card Bill
                              * `C55` – Business Disbursement
                              * `C56` – Government/Non-profit Disbursement
                              * `C57` – Rapid Merchant Settlement
                              * `C59` – Cash-in at Point of Sale
                              * `C65` – General Business-to-Business Transfer
                          enum: ["C07","C52","C53","C54","C55","C56","C57","C59","C65"]
                        localMerchantId:
                          type: string
                          description: Indicates the merchant's SIREN or SIRET if available.
                        userId:
                          type: integer
                          description: The unique identifier of the User who owns the Wallet the card is attached to.
                        authorizationIdResponse:
                          type: string
                          description: A unique identifier generated by the issuing institution during a transaction. 
                          example: "560268"
                          nullable: true
                        isPinValidated:
                          type: boolean
                          description: Whether the PIN was entered and successfully verified.
                          nullable: true
                  cursor:
                    type: object
                    properties:
                      prev:
                        type: string
                        nullable: true
                        description: |
                          Pointer value for previous page. Set to `null` when on the first page.
                        example: "356a192b7913b04c54574d18c28d46e6395428ab"
                      current:
                        type: string
                        nullable: true
                        description: |
                          Pointer for the current page.
                        example: "da4b9237bacccdf19c0760cab7aec4a8359010b0"
                      next:
                        type: string
                        nullable: true
                        description: |
                          Pointer value for next page. Set to `null` when on the first page.
                        example: "da4b9237bacccdf19c0760cab7aec4a8359010b0"
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
  /core-connect/mid/metadata:
    get:
      tags:
        - Merchant ID Metadata
      summary: Get all MID metadata
      description: Retrieve all MID metadata.
      operationId: getAllMidMetadata
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequestError'
      security:
        - OAuth2:
            - admin
            # verified scope
    put:
      tags:
        - Merchant ID Metadata
      summary: Put Bulk metadata
      description: Create or update bulk metadata
      operationId: putMidMetadata
      #parameters:
        #- $ref: '#/components/parameters/Authorization' 
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  mid:
                    type: integer
                additionalProperties:
                  type: string
      responses:
        '204':
          description: The resource was updated successfully.
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - admin
            # verified scope
  /core-connect/mid/{mid}/metadata:
    put:
      tags:
        - Merchant ID Metadata
      summary: Store MID Metadata
      description: Store metadata for a Merchant Id.
      operationId: postMidMetadata
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: mid
          in: path
          description: Mid
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  otp:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      security:
        - OAuth2:
            - admin
            # verified scope
    get:
      tags:
        - Merchant ID Metadata
      summary: Get MID Metadata
      description: Retrieve metadata for a Merchant Id.
      operationId: getMidMetadata
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: mid
          in: path
          description: Mid
          required: true
          schema:
            type: integer
            example: 12345
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      security:
        - OAuth2:
            - admin
  /core-connect/payouts/{payoutId}/proof:
    get:
      tags:
        - Payouts
      summary: Create Payout Proof
      description: | 
        Generate and download a proof of payout in .PDF format. See [Proof of Payout](/guide/transfers/proof-of-payout.html) for more information.
      operationId: getProofPayout
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: payoutId
          in: path
          description: The unique identifier of the Payout.
          required: true
          schema:
            type: string
            example: "12345"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  link:
                    type: string
                    description: The download URL of the proof of payout.
                    example: "https://xxx.s3.eu-west-3.amazonaws.com/tmp/xxx.pdf"
                  expireIn:
                    type: integer
                    description: The time after which the download link expires (in seconds).
                    example: 300
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
  /core-connect/card/bulk/{orderId}/report:
    get:
      tags:
        - Cards Bulk Creation
        - Card User Bulk Creation
      summary: Get Report
      description: |
        Get a link to download the bulk creation report. This endpoint is used for both [Card Bulk Creation](/guide/cards/creation.html#bulk-creation) and [Card User Bulk Creation](/guide/cards/creation.html#creating-users-and-cards-from-csv) orders.

        The link expires after 5 minutes.

        |     |     |
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `admin` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getCardBulkReport
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: orderId
          in: path
          description: The unique identifier of the bulk creation order (Card Bulk or Card User Bulk).
          required: true
          schema:
            type: string
            format: uuid
            example: "4b76d52b-72a5-4a18-a134-8e8e78d1284a"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    description: The URL for downloading the report.
                    example: "https://xxx.s3.eu-west-3.amazonaws.com/cards/xxx[...]"
                  expireIn:
                    type: integer
                    description: The time after which the download link expires (in seconds).
                    default: 300
                    example: 300
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - admin
  /core-connect/card/bulk:
    post:
      tags:
        - Cards Bulk Creation
      summary: Create Bulk Card Order
      description: |
        Create a Bulk Card order to create multiple cards at once.

        |     |     |
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `admin` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: postBulkCard
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - number
                - medium
              properties:
                number:
                  type: integer
                  description: |
                    The number of cards to be created. There may be limitations to the maximum number of cards you can create at once.
                userIdOwner:
                  type: integer
                  description: |
                    The unique identifier of the user owning the cards. Required if `createUserForEach` is set to `false` or undefined.
                createUserForEach:
                  type: boolean
                  description: |
                    Whether to automatically create users for each created card.
                distributionCountry:
                  type: string
                  nullable: true
                  description: |
                    The country in which the end user is using your services. Available values may vary depending on your configuration, see [Distribution Country](/guide/users/introduction.html#distribution-country-distributioncountry) for more information.
                    This field is only required when you operate in multiple countries and if `createUserForEach` is set to `true`.
                  format: ISO 3166-1 alpha-2
                  example: "FR"
                  enum:
                    - FR
                    - ES
                    - IT
                    - DE
                    - BE
                    - NL
                walletIdAttach:
                  type: integer
                  description: |
                    The unique identifier of the Wallet the cards are going to be attached to. Required if `createWalletForEach` is set to `false`.
                createWalletForEach:
                  type: boolean
                  description: |
                    Whether to create one Wallet per card.
                walletTypeId:
                  type: integer
                  description: |
                    The type of Wallet the card are going to be attached to. Learn more in the [Wallet Types](/guide/wallets/introduction.html#types-of-wallets) documentation.
                  enum: [9,10,15]
                medium:
                  type: integer
                  description: |
                    The type of cards to create depending on your Card Program. Can be:
                    * `1` – Physical
                    * `2` – Virtual
                    * `3` – Virtual to Physical
                  enum: [1,2,3]
                cardPrint:
                  type: string
                  description: |
                    The [Card Program](/guide/cards/introduction.html#card-program) to associate to the Card and the options provided with it. This information is shared with you by Treezor.
                anonymous:
                  type: integer
                  description: |
                    Whether the cards are to belong to [Anonymous Users](/guide/users/physical.html#anonymous-users). If so set the value to `1`, otherwise `0`.
                    When set to `1`, there is no embossed name on the card.
                  enum: [0,1]
                defaultPermsGroup:
                  type: string
                  description: |
                    A code for a [preset of permissions](/guide/cards/restrictions-limits.html#options-permission-groups). It indicates whether the card main options (contactless, online payments, withdrawals, and international payments) are activated or not.
                  enum:
                    - TRZ-CU-001
                    - TRZ-CU-002
                    - TRZ-CU-003
                    - TRZ-CU-004
                    - TRZ-CU-005
                    - TRZ-CU-006
                    - TRZ-CU-007
                    - TRZ-CU-008
                    - TRZ-CU-009
                    - TRZ-CU-010
                    - TRZ-CU-011
                    - TRZ-CU-012
                    - TRZ-CU-013
                    - TRZ-CU-014
                    - TRZ-CU-015
                    - TRZ-CU-016
                defaultMccRestrictionGroupId:
                  type: integer
                  description: |
                    The unique identifier of the MCC Restriction Group to associate with the cards.
                defaultMerchantRestrictionGroupId:
                  type: integer
                  description: |
                    The unique identifier of the MID Restriction Group to associate with the cards.
                defaultCountryRestrictionGroupId:
                  type: integer
                  description: |
                    The unique identifier of the Country Restriction Group to associate with the cards.
                packageId:
                  type: string
                  maxLength: 8
                  description: Packaging reference for card shipping.
                  example: "Pkg123"
                logoId:
                  type: string
                  maxLength: 30
                  description: |
                    The file name of the logo for the card, as uploaded to the manufacturer. Learn more in the [Logo](/guide/cards/creation.html#logo-logoid) article.
                  example: "MyLogoFile.png"
                paymentDailyLimit:
                  type: number
                  description: |
                    POS operations limit for a single day including cents. The decimal delimiter must be ".". No default value.
                    For food vouchers use cases only.
                limitPaymentAll:
                  type: integer
                  description: POS operations limit from beginning. No default value.
                limitPaymentDay:
                  type: integer
                  default: 2000
                  description: POS operations limit for a single day.
                limitPaymentWeek:
                  type: integer
                  default: 3000
                  description: POS operations limit for a sliding week.
                limitPaymentMonth:
                  type: integer
                  description: POS operations limit for a sliding month. No default value.
                limitPaymentYear:
                  type: integer
                  description: POS operations limit for a sliding year. No default value.
                limitAtmAll:
                  type: integer
                  description: ATM operations limit from beginning. No default value.
                limitAtmDay:
                  type: integer
                  default: 1000
                  description: ATM operations limit for a single day.
                limitAtmWeek:
                  type: integer
                  default: 2000
                  description: ATM operations limit for a sliding week.
                limitAtmMonth:
                  type: integer
                  description: ATM operations limit for a sliding month. No default value.
                limitAtmYear:
                  type: integer
                  description: ATM operations limit for a sliding year. No default value.
                cardDeliveryAddress1:
                  type: string
                  description: |
                    See [address formats](/guide/api-basics/data-format.html#addresses) for limitations.
                cardDeliveryAddress2:
                  type: string
                  description: |
                    See [address formats](/guide/api-basics/data-format.html#addresses) for limitations.
                cardDeliveryAddress3:
                  type: string
                  description: |
                    See [address formats](/guide/api-basics/data-format.html#addresses) for limitations.
                cardDeliveryPostCode:
                  type: string
                  description: The postcode of the address.
                cardDeliveryCity:
                  type: string
                  description: The city of the address.
                cardDeliveryState:
                  type: string
                  description: The state of the address (supported by Idemia only).
                cardDeliveryCountry:
                  type: string
                  description: The country of the address.
                pin:
                  type: string
                  maxLength: 4
                  nullable: true
                  example: "1234"
                designCode:
                  type: string
                  format: alphanumeric
                  maxLength: 2
                  description: |
                    Customization code for the card design. If missing, falls back to the default Design Code. Learn more in the [Designs](/guide/cards/creation.html#designs-designcode) article.
                  nullable: true
                  example: "2"
                cardLanguage:
                  type: string
                  format: ISO 639-1 alpha-2
                  maxLength: 8
                  description: |
                    The language preferences for the card for [ATMs](/guide/overview/glossary.html#automated-teller-machine-atm), in the order of preference. For instance, for French and English, you have to enter "fren".

                    While this information is well taken into account in the card configuration, please note that the API will not return the value.
                      
                    Must be alphabetic and max. 8 characters. Format: [ISO 639-1 alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).
                  example: "fren"
                batchDeliveryId:
                  type: number
                  description: |
                    Allows you to group Cards shipping together by specifying the same delivery ID to multiple Cards.
                  maximum: 238327
                  minimum: 1
                  nullable: true
                sendToParent:
                  type: integer
                  description: |
                    Allows you to send the Card to the parent User, if defined to 1.
                  enum: [0,1]
                customizedInfo:
                  type: string
                  maxLength: 50
                  description: |
                    Customized text to be displayed on the card.

                    If populated, it must:
                    * Be alphanumeric
                    * Contain at most 27 characters
                    * Not contain `!"#%'(),:;<>?@[]^` or the backtick symbol.
                letterCustomizedInfo:
                  type: string
                  maxLength: 50
                  description: |
                    Customized text for the letter that is joined to the card.

                    If populated, it must:
                    * Be alphanumeric
                    * Contain at most 50 characters
                    * Not contain `!"#%'(),:;<>?@[]^` or the backtick symbol.
                freeCustomizedInfo:
                  type: string
                  maxLength: 50
                  description: |
                    More customized text to be displayed on the card.

                    If populated, it must:
                    * Be alphanumeric
                    * Contain at most 50 characters
                    * Not contain `!"#%'(),:;<>?@[]^` or the backtick symbol.
                logoBackId:
                  type: string
                  description: |
                    The file name of the logo for the back of the card, as uploaded to the manufacturer. Learn more in the [Back Logo](/guide/cards/creation.html#back-logo-logobackid) article.
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  number:
                    type: integer
                    description: |
                      The number of cards to be created. There may be limitations to the maximum number of cards you can create at once.
                    example: 15
                  userIdOwner:
                    type: integer
                    nullable: true
                  createUserForEach:
                    type: boolean
                    description: |
                      Whether to automatically create users for each created card.
                  distributionCountry:
                    type: string
                    nullable: true
                    description: |
                      The country in which the end user is using your services. Available values may vary depending on your configuration, see [Distribution Country](/guide/users/introduction.html#distribution-country-distributioncountry) for more information.
                      
                      This field is only required when you operate in multiple countries and if `createUserForEach` is set to `true`.
                    format: ISO 3166-1 alpha-2
                    example: "FR"
                    enum:
                      - FR
                      - ES
                      - IT
                      - DE
                      - BE
                      - NL
                  walletIdAttach:
                    type: integer
                    nullable: true
                  createWalletForEach:
                    type: boolean
                    description: Whether one wallet was created per card.
                  walletTypeId:
                    type: integer
                    description: |
                      The type of Wallet the card are going to be attached to. Learn more in the [Wallet Types](/guide/wallets/introduction.html#types-of-wallets) documentation.
                    enum: [9,10,15]
                    nullable: true
                  medium:
                    type: integer
                    description: |
                      The type of cards to create depending on your Card Program. Can be:
                      * `1` – Physical
                      * `2` – Virtual
                      * `3` – Virtual to Physical
                    enum: [1,2,3]
                    nullable: true
                  cardPrint:
                    type: string
                  anonymous:
                    type: integer
                    description: |
                      Whether the cards are to belong to [Anonymous Users](/guide/users/physical.html#anonymous-users). If so set the value to `1`, otherwise `0`.
                      
                      When set to `1`, there is no embossed name on the card.
                    enum: [0,1]
                  defaultPermsGroup:
                    type: string
                    description: |
                      A code for a [preset of permissions](/guide/cards/restrictions-limits.html#options-permission-groups). It indicates whether the card main options (contactless, online payments, withdrawals, and international payments) are activated or not.
                    enum:
                      - TRZ-CU-001
                      - TRZ-CU-002
                      - TRZ-CU-003
                      - TRZ-CU-004
                      - TRZ-CU-005
                      - TRZ-CU-006
                      - TRZ-CU-007
                      - TRZ-CU-008
                      - TRZ-CU-009
                      - TRZ-CU-010
                      - TRZ-CU-011
                      - TRZ-CU-012
                      - TRZ-CU-013
                      - TRZ-CU-014
                      - TRZ-CU-015
                      - TRZ-CU-016
                  defaultMccRestrictionGroupId:
                    type: integer
                    description: |
                      The unique identifier of the MCC Restriction Group to associate with the cards.
                    nullable: true
                  defaultMerchantRestrictionGroupId:
                    type: integer
                    nullable: true
                    description: |
                      The unique identifier of the MID Restriction Group to associate with the cards.
                  defaultCountryRestrictionGroupId:
                    type: integer
                    description: |
                      The unique identifier of the Country Restriction Group to associate with the cards.
                    nullable: true
                  packageId:
                    type: string
                    maxLength: 8
                    description: Packaging reference for card shipping.
                    example: "Pkg123"
                    nullable: true
                  logoId:
                    type: string
                    maxLength: 30
                    description: |
                      The file name of the logo for the card, as uploaded to the manufacturer. Learn more in the [Logo](/guide/cards/creation.html#logo-logoid) article.
                    example: MyLogoFile.png
                    nullable: true
                  paymentDailyLimit:
                    type: integer
                    nullable: true
                  limitPaymentAll:
                    type: integer
                    nullable: true
                    description: | 
                      POS operations limit of the corresponding card for a single day.

                      See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                    example: 2000
                  limitPaymentDay:
                    type: integer
                    nullable: true
                    description: | 
                      POS operations limit of the corresponding card for a single day.

                      See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                    example: 2000
                  limitPaymentWeek:
                    type: integer
                    nullable: true
                    description: | 
                      POS operations limit of the corresponding card for a sliding week.

                      See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                    example: 3000
                  limitPaymentMonth:
                    type: integer
                    nullable: true
                    description: | 
                      POS operations limit of the corresponding card for a sliding month.

                      See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                    example: 0
                  limitPaymentYear:
                    type: integer
                    nullable: true
                    description: |
                      POS operations limit of the corresponding card for a sliding year.

                      See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                    example: 0
                  limitAtmAll:
                    type: integer
                    nullable: true
                    description: | 
                      ATM operations limit of the corresponding card from beginning.

                      See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                    example: 0
                  limitAtmDay:
                    type: integer
                    nullable: true
                    description: | 
                      ATM operations limit of the corresponding card for a single day.

                      See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                    example: 1000
                  limitAtmWeek:
                    type: integer
                    nullable: true
                    description: | 
                      ATM operations limit of the corresponding card for a sliding week.

                      See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                    example: 2000
                  limitAtmMonth:
                    type: integer
                    nullable: true
                    description: | 
                      ATM operations limit of the corresponding card for a sliding month.

                      See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                    example: 0
                  limitAtmYear:
                    type: integer
                    nullable: true
                    description: | 
                      The ATM operations limit of the corresponding card for a sliding year.

                      See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                    example: 0
                  cardDeliveryAddress1:
                    type: string
                    description: |
                      See [address formats](/guide/api-basics/data-format.html#addresses) for limitations.
                  cardDeliveryAddress2:
                    type: string
                    description: |
                      See [address formats](/guide/api-basics/data-format.html#addresses) for limitations.
                  cardDeliveryAddress3:
                    type: string
                    description: |
                      See [address formats](/guide/api-basics/data-format.html#addresses) for limitations.
                  cardDeliveryPostCode:
                    type: string
                    description: The postcode of the address.
                  cardDeliveryCity:
                    type: string
                    description: The city of the address.
                  cardDeliveryState:
                    type: string
                    description: The state of the address (supported by Idemia only).
                  cardDeliveryCountry:
                    type: string
                    description: The country of the address.
                  pin:
                    description: |
                      The Card PIN code. Treezor recommends you set this value when creating the card, but if not, a random value is set by default.
                    type: string
                    maxLength: 4
                    nullable: true
                    example: "1234"
                  designCode:
                    type: string
                    format: alphanumeric
                    maxLength: 2
                    description: |
                      Customization code for the card design. If missing, falls back to the default Design Code. Learn more in the [Designs](/guide/cards/creation.html#designs-designcode) article.
                    nullable: true
                    example: "2"
                  cardLanguage:
                    type: string
                    maxLength: 8
                    description: |
                      Specifies a maximum of 4 preferred languages used to communicate with the cardholder on ATMs. Expected as ISO 639-1 (code alpha-2) concatenated by priority (e.g., nrfrenes for Dutch 1st, French 2nd, English 3rd, Spanish 4th)..
                    nullable: true
                    example: nrfrenes
                  batchDeliveryId:
                    type: number
                    description: |
                      Allows you to group Cards shipping together by specifying the same delivery ID to multiple Cards.
                    maximum: 238327
                    minimum: 1
                    nullable: true
                  sendToParent:
                    type: integer
                    description:  Whether the card should be sent to the cardholder's Parent User. 
                    enum: [0,1]
                  customizedInfo:
                    type: string
                    maxLength: 50
                    description: |
                      Customized text to be displayed on the card.

                      If populated, it must:
                      * Be alphanumeric
                      * Contain at most 27 characters
                      * Not contain `!"#%'(),:;<>?@[]^` or the backtick symbol.
                  letterCustomizedInfo:
                    type: string
                    maxLength: 50
                    description: |
                      Customized text for the letter that is joined to the card.

                      If populated, it must:
                      * Be alphanumeric
                      * Contain at most 50 characters
                      * Not contain `!"#%'(),:;<>?@[]^` or the backtick symbol.
                  freeCustomizedInfo:
                    type: string
                    maxLength: 50
                    description: |
                      More customized text to be displayed on the card.

                      If populated, it must:
                      * Be alphanumeric
                      * Contain at most 50 characters
                      * Not contain `!"#%'(),:;<>?@[]^` or the backtick symbol.
                  logoBackId:
                    type: string
                    maxLength: 30
                    description: |
                      The file name of the logo for the back of the card, as uploaded to the manufacturer. Learn more in the [Back Logo](/guide/cards/creation.html#back-logo-logobackid) article.
                    nullable: true
                    example: "MyBackLogoFile.png"
                  orderId:
                    type: string
                    format: uuid
                    description: The unique identifier of the card bulk order.
                    example: "4b76d52b-72a5-4a18-a134-8e8e78d1284a"
                  status:
                    type: string
                    description: The status of the order.
                    enum:
                      - COMPLETE
                      - COMPLETE_WITH_ERRORS
                      - PENDING
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - admin
    get:
      tags:
        - Cards Bulk Creation
      summary: List Bulk Card Orders
      description: |
        List bulk card orders.

        |     |     |
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `admin` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getBulkCard
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: designCode
          in: query
          description: |
            Customization code for the card design. If missing, falls back to the default Design Code. Learn more in the [Designs](/guide/cards/creation.html#designs-designcode) article.
          required: true
          schema:
            type: string
            format: alphanumeric
            maxLength: 2
            example: "2"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    orderId:
                      type: string
                      format: uuid
                      description: The unique identifier of the card bulk order.
                      example: 4b76d52b-72a5-4a18-a134-8e8e78d1284a
                    walletIdAttach:
                      type: integer
                      description: |
                        The unique identifier of the Wallet the cards are going to be attached to. Required if `createWalletForEach` is set to `false`.
                      nullable: true
                    createWalletForEach:
                      type: boolean
                      description: |
                        Whether to automatically create wallets for each created card.
                    walletTypeId:
                      type: integer
                      description: |
                        The type of Wallet the card are going to be attached to. Learn more in the [Wallet Types](/guide/wallets/introduction.html#types-of-wallets) documentation.
                      enum: [9,10,15]
                      nullable: true
                    userIdOwner:
                      type: integer
                      description: |
                        The unique identifier of the user owning the cards. Required if `createUserForEach` is set to `false` or undefined.
                      nullable: true
                    createUserForEach:
                      type: boolean
                      description: |
                        Whether to automatically create users for each created card.
                    distributionCountry:
                      type: string
                      nullable: true
                      description: |
                        The country in which the end user is using your services. Available values may vary depending on your configuration, see [Distribution Country](/guide/users/introduction.html#distribution-country-distributioncountry) for more information.
                        This field is only required when you operate in multiple countries and if `createUserForEach` is set to `true`.
                      format: ISO 3166-1 alpha-2
                      example: "FR"
                      enum:
                        - FR
                        - ES
                        - IT
                        - DE
                        - BE
                        - NL
                    number:
                      type: integer
                      description: |
                        The number of cards to be created. There may be limitations to the maximum number of cards you can create at once.
                      example: 15
                    defaultMccRestrictionGroupId:
                      type: integer
                      description: |
                        The unique identifier of the MCC Restriction Group to associate with the cards.
                      nullable: true
                    defaultMerchantRestrictionGroupId:
                      type: integer
                      description: |
                        The unique identifier of the MID Restriction Group to associate with the cards.
                      nullable: true
                    defaultCountryRestrictionGroupId:
                      type: integer
                      description: |
                        The unique identifier of the Country Restriction Group to associate with the cards.
                      nullable: true
                    defaultPermsGroup:
                      type: string
                      description: |
                        A code for a [preset of permissions](/guide/cards/restrictions-limits.html#options-permission-groups). It indicates whether the card main options (contactless, online payments, withdrawals, and international payments) are activated or not.
                      enum:
                        - TRZ-CU-001
                        - TRZ-CU-002
                        - TRZ-CU-003
                        - TRZ-CU-004
                        - TRZ-CU-005
                        - TRZ-CU-006
                        - TRZ-CU-007
                        - TRZ-CU-008
                        - TRZ-CU-009
                        - TRZ-CU-010
                        - TRZ-CU-011
                        - TRZ-CU-012
                        - TRZ-CU-013
                        - TRZ-CU-014
                        - TRZ-CU-015
                        - TRZ-CU-016
                    status:
                      type: string
                      description: The status of the order.
                      enum:
                        - COMPLETE
                        - COMPLETE_WITH_ERRORS
                        - PENDING
                    createdAt:
                      type: string
                      format: date-time
                      description: The date and time at which the Bulk Card creation order was created.
                      example: "2025-03-24T08:40:25+01:00"
                    errors:
                      type: array
                      items:
                        type: string
                    packageId:
                      type: string
                      maxLength: 8
                      description: Packaging reference for card shipping.
                      example: "Pkg123"
                      nullable: true
                    logoId:
                      type: string
                      maxLength: 30
                      description: |
                        The file name of the logo for the card, as uploaded to the manufacturer. Learn more in the [Logo](/guide/cards/creation.html#logo-logoid) article.
                      nullable: true
                      example: "MyLogoFile.png"
                    anonymous:
                      type: integer
                      description: |
                        Whether the cards are to belong to [Anonymous Users](/guide/users/physical.html#anonymous-users). If so set the value to `1`, otherwise `0`.
                        When set to `1`, there is no embossed name on the card.
                      enum: [0,1]
                    cardPrint:
                      type: string
                      description: |
                          The [Card Program](/guide/cards/introduction.html#card-program) to associate to the Card and the options provided with it. This information is shared with you by Treezor.
                    paymentDailyLimit:
                      type: integer
                      nullable: true
                    limitPaymentAll:
                      type: integer
                      description: | 
                        POS operations limit of the corresponding card for a single day.

                        See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                      example: 2000
                      nullable: true
                    limitPaymentDay:
                      type: integer
                      description: | 
                        POS operations limit of the corresponding card for a single day.

                        See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                      example: 2000
                      nullable: true
                    limitPaymentWeek:
                      type: integer
                      nullable: true
                      description: | 
                        POS operations limit of the corresponding card for a sliding week.

                        See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                      example: 3000
                    limitPaymentMonth:
                      type: integer
                      nullable: true
                      description: | 
                        POS operations limit of the corresponding card for a sliding month.

                        See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                      example: 0
                    limitPaymentYear:
                      type: integer
                      nullable: true
                      description: |
                        POS operations limit of the corresponding card for a sliding year.

                        See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                      example: 0
                    limitAtmAll:
                      type: integer
                      nullable: true
                      description: | 
                        ATM operations limit of the corresponding card from beginning.

                        See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                      example: 0
                    limitAtmDay:
                      type: integer
                      nullable: true
                      description: | 
                        ATM operations limit of the corresponding card for a single day.

                        See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                      example: 1000
                    limitAtmWeek:
                      type: integer
                      nullable: true
                      description: | 
                        ATM operations limit of the corresponding card for a sliding week.

                        See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                      example: 2000
                    limitAtmMonth:
                      type: integer
                      nullable: true
                      description: | 
                        ATM operations limit of the corresponding card for a sliding month.

                        See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                      example: 0
                    limitAtmYear:
                      type: integer
                      nullable: true
                      description: | 
                        The ATM operations limit of the corresponding card for a sliding year.

                        See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                      example: 0
                    medium:
                      type: integer
                      description: |
                        The type of cards to create depending on your Card Program. Can be:
                        * `1` – Physical
                        * `2` – Virtual
                        * `3` – Virtual to Physical
                      enum: [1,2,3]
                      nullable: true
                    cardDeliveryAddress1:
                      type: string
                      description: |
                        See [address formats](/guide/api-basics/data-format.html#addresses) for limitations.
                      example: "14 Willow lanes"
                    cardDeliveryAddress2:
                      type: string
                      description: |
                        See [address formats](/guide/api-basics/data-format.html#addresses) for limitations.
                    cardDeliveryAddress3:
                      type: string
                      description: |
                        See [address formats](/guide/api-basics/data-format.html#addresses) for limitations.
                    cardDeliveryPostCode:
                      type: string
                      description: The postcode of the address.
                    cardDeliveryCity:
                      type: string
                      description: The city of the address.
                      example: "Paris"
                    cardDeliveryState:
                      type: string
                      description: The state of the address (supported by Idemia only).
                    cardDeliveryCountry:
                      type: string
                      description: The country of the address.
                      example: "FR"
                    pin:
                      type: string
                      maxLength: 4
                      nullable: true
                      example: "1234"
                    designCode:
                      type: string
                      format: alphanumeric
                      maxLength: 2
                      description: |
                        Customization code for the card design. If missing, falls back to the default Design Code. Learn more in the [Designs](/guide/cards/creation.html#designs-designcode) article.
                      nullable: true
                      example: "2"
                    cardLanguage:
                      type: string
                      format: ISO 639-1 alpha-2
                      maxLength: 8
                      description: |
                        The language preferences for the card for [ATMs](/guide/overview/glossary.html#automated-teller-machine-atm), in the order of preference. For instance, for French and English, you have to enter "fren".

                        While this information is well taken into account in the card configuration, please note that the API will not return the value.
                        
                        Must be alphabetic and max. 8 characters. Format: [ISO 639-1 alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).
                      example: "fren"
                    batchDeliveryId:
                      type: number
                      description: |
                        Allows you to group Cards shipping together by specifying the same delivery ID to multiple Cards.
                      maximum: 238327
                      minimum: 1
                      nullable: true
                    sendToParent:
                      type: integer
                      description: |
                        Allows you to send the Card to the parent User, if defined to 1.
                      enum: [0,1]
                    customizedInfo:
                      type: string
                      maxLength: 50
                      description: |
                        Customized text to be displayed on the card.

                        If populated, it must:
                        * Be alphanumeric
                        * Contain at most 27 characters
                        * Not contain `!"#%'(),:;<>?@[]^` or the backtick symbol.
                    letterCustomizedInfo:
                      type: string
                      maxLength: 50
                      description: |
                        Customized text for the letter that is joined to the card.

                        If populated, it must:
                        * Be alphanumeric
                        * Contain at most 50 characters
                        * Not contain `!"#%'(),:;<>?@[]^` or the backtick symbol.
                    freeCustomizedInfo:
                      type: string
                      maxLength: 50
                      description: |
                        More customized text to be displayed on the card.
                        
                        If populated, it must:
                        * Be alphanumeric
                        * Contain at most 50 characters
                        * Not contain `!"#%'(),:;<>?@[]^` or the backtick symbol.
                    logoBackId:
                      type: string
                      description: |
                        The file name of the logo for the back of the card, as uploaded to the manufacturer. Learn more in the [Back Logo](/guide/cards/creation.html#back-logo-logobackid) article.
                      nullable: true
                    successCardsCount:
                      type: integer
                      description: |
                        The number of card creation successes.
                      example: 5
                    errorCardsCount:
                      type: integer
                      description: |
                        The number of card creation errors.
                      example: 10
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - admin

  /core-connect/card/user/bulk/validate:
    post:
      tags:
        - Card User Bulk Creation
      summary: Validate CSV File
      description: |
        Validate a CSV file before launching the bulk user and card creation process. This endpoint checks the file content (required fields, formats, referentials) without creating any resource or order.

        Use this endpoint to preview and fix errors before submitting the file for order creation. The [Create Order](/api-reference/api-endpoints.html#tag/Card%20User%20Bulk%20Creation/createCardUserBulkOrder){target="_self"} endpoint performs the same validation and rejects files with any invalid line.

        The response includes a global file status and a link to download an enriched CSV with an error column per line. The link expires after 5 minutes.

        |     |     |
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `admin` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: validateCardUserBulkFile
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: |
                    The CSV file to validate. Must contain the required column headers. Max size: 10 MB (~5,000 lines).
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  fileStatus:
                    type: string
                    description: |
                      The global validation status of the file:
                      * `OK` – All lines are valid
                      * `PARTIAL_OK` – Some lines have errors
                      * `KO` – All lines have errors or the file structure is invalid
                    enum:
                      - OK
                      - PARTIAL_OK
                      - KO
                    example: "PARTIAL_OK"
                  totalLines:
                    type: integer
                    description: The total number of data lines in the CSV file.
                    example: 10
                  validLines:
                    type: integer
                    description: The number of lines that passed validation.
                    example: 8
                  invalidLines:
                    type: integer
                    description: The number of lines that failed validation.
                    example: 2
                  reportLink:
                    type: string
                    description: |
                      The URL to download the enriched CSV file with an `errors` column. The link expires after 300 seconds.
                    example: "https://sbx-connect-files.s3.eu-west-3.amazonaws.com/card-issuing/validate/pre-process-report.csv?X-Amz-Expires=300&..."
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - admin

  /core-connect/card/user/bulk:
    post:
      tags:
        - Card User Bulk Creation
      summary: Create Bulk User and Card Order
      description: |
        Submit a CSV file to create users and cards in bulk. Each line in the CSV represents one user and one card to be created.

        The file must be 100% valid. The endpoint performs the same validation as the [Validate CSV](/api-reference/api-endpoints.html#tag/Card%20User%20Bulk%20Creation/validateCardUserBulkFile){target="_self"} endpoint and rejects the request with a `400` error if any line is invalid. Use the validation endpoint first to identify and fix errors.

        The order is created with `status: "CREATED"` and immediately transitions to `RUNNING` once the asynchronous processing starts. Use the [List Orders](/api-reference/api-endpoints.html#tag/Card%20User%20Bulk%20Creation/getCardUserBulkOrders){target="_self"} endpoint to monitor progress.

        |     |     |
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `admin` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: createCardUserBulkOrder
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - orderName
                - walletId
              properties:
                file:
                  type: string
                  format: binary
                  description: |
                    The CSV file containing user and card data. Must contain the required column headers. Max size: 10 MB (~5,000 lines).
                orderName:
                  type: string
                  description: A functional name for the processing order, for your own reference.
                  example: "Cherrywood Travel - Compensation Batch 1"
                walletId:
                  type: integer
                  description: |
                    The unique identifier of the Wallet to which the created cards will be linked. The Wallet must be active (`VALIDATED`) and belong to a KYC-validated, non-restricted user.
                  example: 923119
                activateCards:
                  type: boolean
                  description: |
                    Whether to automatically activate the cards after creation.
                  default: false
                enrollOtpSms:
                  type: boolean
                  description: |
                    Whether to automatically enroll the cards for OTP SMS (3DS) using the `mobile` field from the CSV.
                  default: false
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  orderId:
                    type: string
                    format: uuid
                    description: The unique identifier of the bulk order.
                    example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                  orderName:
                    type: string
                    description: The functional name of the order.
                    example: "Cherrywood Travel - Compensation Batch 1"
                  walletId:
                    type: integer
                    description: The unique identifier of the target Wallet.
                    example: 923119
                  activateCards:
                    type: boolean
                    description: Whether cards will be activated after creation.
                    example: true
                  enrollOtpSms:
                    type: boolean
                    description: Whether cards will be enrolled for OTP SMS.
                    example: true
                  status:
                    type: string
                    description: The status of the order.
                    enum:
                      - CREATED
                    example: "CREATED"
                  createdAt:
                    type: string
                    format: date-time
                    description: |
                      The date and time at which the order was created.
                      Format: `YYYY-MM-DDTHH:mm:ssZ`
                    example: "2026-04-03T10:00:00Z"
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - admin
    get:
      tags:
        - Card User Bulk Creation
      summary: List Bulk User and Card Orders
      description: |
        List all bulk user and card creation orders. Results can be filtered by date, order name, and status.

        |     |     |
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `admin` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getCardUserBulkOrders
      parameters:
        - name: status
          in: query
          description: Filter by order status.
          required: false
          schema:
            type: string
            enum:
              - CREATED
              - RUNNING
              - RUNNING_WITH_ERROR
              - COMPLETE
              - COMPLETE_WITH_ERROR
        - name: orderName
          in: query
          description: Filter by functional name (partial match).
          required: false
          schema:
            type: string
        - name: dateFrom
          in: query
          description: |
            Filter orders created from this date.
            Format: `YYYY-MM-DD`
          required: false
          schema:
            type: string
            format: date
            example: "2026-01-01"
        - name: dateTo
          in: query
          description: |
            Filter orders created up to this date.
            Format: `YYYY-MM-DD`
          required: false
          schema:
            type: string
            format: date
            example: "2026-12-31"
        - name: cursor
          in: query
          description: |
            Pagination cursor. If omitted, results start from the first page. Use the `cursor` value from the response to retrieve the next page.
          required: false
          schema:
            type: string
            example: "eyJMYXN0RXZhbHVhdGVkS2V5Ijp7Il..."
        - name: pageSize
          in: query
          description: |
            Number of results per page.
          required: false
          schema:
            type: integer
            default: 50
            example: 10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        orderId:
                          type: string
                          format: uuid
                          description: The unique identifier of the bulk order.
                          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                        orderName:
                          type: string
                          description: The functional name of the order.
                          example: "Cherrywood Travel - Compensation Batch 1"
                        status:
                          type: string
                          description: |
                            The status of the order:
                            * `CREATED` – Order created, processing not yet started
                            * `RUNNING` – Processing in progress
                            * `RUNNING_WITH_ERROR` – Processing in progress with some errors
                            * `COMPLETE` – Processing completed successfully
                            * `COMPLETE_WITH_ERROR` – Processing completed with some errors
                          enum:
                            - CREATED
                            - RUNNING
                            - RUNNING_WITH_ERROR
                            - COMPLETE
                            - COMPLETE_WITH_ERROR
                          example: "COMPLETE"
                        createdAt:
                          type: string
                          format: date-time
                          description: |
                            The date and time at which the order was created.
                            Format: `YYYY-MM-DDTHH:mm:ssZ`
                          example: "2026-04-03T10:00:00Z"
                        walletId:
                          type: integer
                          description: The unique identifier of the target Wallet.
                          example: 923119
                        activateCards:
                          type: boolean
                          description: Whether cards are activated after creation.
                          nullable: true
                          example: true
                        enrollOtpSms:
                          type: boolean
                          description: Whether cards are enrolled for OTP SMS.
                          nullable: true
                          example: true
                        totalLines:
                          type: integer
                          description: The total number of lines in the CSV file.
                          example: 10
                        successLines:
                          type: integer
                          description: The number of lines processed successfully.
                          example: 10
                        failedLines:
                          type: integer
                          description: The number of lines that failed processing.
                          example: 0
                        errorMessage:
                          type: string
                          description: The error message for orders with errors. Only populated for orders with `COMPLETE_WITH_ERROR` or `RUNNING_WITH_ERROR` status.
                          nullable: true
                          example: null
                  cursor:
                    type: string
                    description: Pagination cursor for retrieving the next page of results.
                    nullable: true
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - admin

  /core-connect/operations/{walletId}/report:
    get:
      tags:
        - Operations
      summary: Get Operations Report
      description: | 
        Retrieve an Operations Report based on the corresponding Wallet `id`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getOperationsReport
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - in: path
          name: walletId
          required: true
          schema:
            type: integer
            example: 12345
          description: The unique identifier of the Wallet.
        - in: query
          name: dateFrom
          required: true
          description: |
            The date and time from which the operations are taken into account for the report.
            The dates are to be html encoded (e.g., 2024-01-11T11:25:36+01:00 becomes `2024-01-11T11:25:36%2B01:00`)
          schema:
            type: string
            format: RFC 3339 date-time
            example: "2024-06-05T00:00:00%2B02:00"
        - in: query
          name: dateTo
          required: true
          description: | 
            The date and time up to which the operations are taken into account for the report.
            The dates are to be html encoded (e.g., 2024-01-11T11:25:36+01:00 becomes `2024-01-11T11:25:36%2B01:00`)
          schema:
            type: string
            format: RFC 3339 date-time
            example: "2024-07-05T00:00:00%2B02:00"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Status of the report.
                    enum:
                      - COMPLETED
                      - CREATED
                  url:
                    type: string
                    description: Download URL for the report once completed.
                    example: "https://env-files.s3.eu-west-3.amazonaws.com/operation/report/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx.csv"
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    post:
      tags:
        - Operations
      summary: Create Operations Report
      description: |
        Create a CSV export that includes all operations for a given Wallet on a given period.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: postOperationsReport
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - in: path
          name: walletId
          required: true
          schema:
            type: integer
            example: 12345
          description: The unique identifier of the Wallet.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - dateFrom
                - dateTo
              properties:
                dateFrom:
                  type: string
                  description: |
                    The start date and time from which the operations are taken into account for the report.
                    Format: `YYYY-MM-DDTHH:mm:ssZ`
                  example: "2024-06-05T00:00:00+02:00"
                dateTo:
                  type: string
                  description: |
                    The end date and time up to which the operations are taken into account for the report.
                    Format: `YYYY-MM-DDTHH:mm:ssZ`
                  example: "2024-07-05T00:00:00+02:00"
                amountFrom:
                  type: integer
                  description: The minimum amount (in cents) of the operations to include in the report.
                  example: 1000
                amountTo:
                  type: integer
                  description: The maximum amount (in cents) of the operations to include in the report.
                  example: 50000
                status:
                  type: array
                  description: Filters operations by status. Returns all statuses when not specified.
                  items:
                    type: string
                    enum:
                      - AUTHORIZED
                      - CANCELED
                      - DECLINED
                      - SETTLED
                initialFlow:
                  type: array
                  description: Filters operations by initial flow. Returns all flows when not specified.
                  items:
                    type: string
                    enum:
                      - cardTransaction
                      - chargeback
                      - payin
                      - payinRefund
                      - payout
                      - payoutRefund
                      - transfer
                operationType:
                  type: array
                  description: Filters operations by type. Returns all types when not specified.
                  items:
                    type: string
                    enum:
                      - bankDirectDebit
                      - bankTransfer
                      - cardTopup
                      - cardTransaction
                      - check
                      - creditNote
                      - fees
                      - intBankTransfer
                      - instantBankTransfer
                      - other
                      - payinRefund
                      - payoutRefund
                      - transferRefund
                      - walletTransfer
                direction:
                  type: string
                  description: Filters operations by direction. Returns both directions when not specified.
                  enum:
                    - CREDIT
                    - DEBIT
      responses:
        '201':
          description: Created
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
  /core-connect/merchantIdRestrictionGroups/{groupId}/mid/metadata:
    get:
      tags:
        - Merchant ID Metadata
      summary: Get all MID with metadata
      description: Retrieve all Merchant Ids with metadata. 
      operationId: getAllMidMetadataBYyGroup
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - in: path
          name: groupId
          required: true
          schema:
            type: integer
            example: 12345
          description: group Id
        - in: query
          name: cursor
          description: Pagination cursor, if you don't pass a cursor, result will start at the first page.
          schema:
            type: string
            example: "da4b9237bacccdf19c0760cab7aec4a8359010b0"
        - in: query
          name: pageSize
          schema:
            type: integer
          description: Number of results per page.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
        '400':
          $ref: '#/components/responses/BadRequestError'
      security:
        - OAuth2:
            - read_write
  /customization/templates:
    get: 
      tags:
        - API Templates
      summary: Get Available Templates
      description: Retrieve the list of templates.
      operationId: getTemplates
      # parameters:
        #- $ref: '#/components/parameters/Authorization'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: The list of templates.
                properties:
                  templates:
                    type: array
                    items:
                      type: string
                    example:
                      - "wallet.address_details"
                      - "wallet.balance_certificate"
                      - "wallet.closure_certificate"
                      - "wallet.confirmationLetter"
                      - "wallet.domiciliation_certificate"
                      - "payout.proof_of_payout"
                      - "wallet.statement"
                      - "email.user.onboarding_confirmation_html"
                      - "email.user.onboarding_confirmation_text"
                      - "email.user.password_forgot_html"
                      - "email.user.password_forgot_text"
      security:
        - OAuth2:
          - admin
  /customization/templates/{templateName}:
    get:
      tags:
        - API Templates
      summary: Get Template Variables
      description: Retrieve the list of variables for the given template
      operationId: getTemplateVariables
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: templateName
          in: path
          description: The name of the Template.
          required: true
          schema:
            type: string
            example: "wallet.statement"
            enum:
              - wallet.address_details
              - wallet.balance_certificate
              - wallet.closure_certificate
              - wallet.confirmationLetter
              - wallet.domiciliation_certificate
              - payout.proof_of_payout
              - wallet.statement
              - email.user.onboarding_confirmation_html
              - email.user.onboarding_confirmation_text
              - email.user.password_forgot_html
              - email.user.password_forgot_text
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: The variables of the template.
                oneOf:
                  - $ref: '#/components/schemas/WalletStatementTemplate'
                  - $ref: '#/components/schemas/WalletAddressDetailsTemplate'
                  - $ref: '#/components/schemas/PayoutProofOfPayoutTemplate'
                  - $ref: '#/components/schemas/EmailUserOnboardingConfirmationHtmlTemplate'
                  - $ref: '#/components/schemas/EmailUserOnboardingConfirmationTextTemplate'
                  - $ref: '#/components/schemas/EmailUserPasswordForgotHtmlTemplate'
                  - $ref: '#/components/schemas/EmailUserPasswordForgotTextTemplate'
                  - $ref: '#/components/schemas/WalletBalanceTemplate'
                  - $ref: '#/components/schemas/WalletConfirmationLetterTemplate'
                  - $ref: '#/components/schemas/WalletClosureTemplate'
                  - $ref: '#/components/schemas/WalletDomiciliationTemplate'
      security:
        - OAuth2:
            - admin
    delete:
      tags:
        - API Templates
      summary: Delete Template
      description: Delete a Template.
      operationId: deleteTemplate
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: templateName
          in: path
          description: The name of the Template.
          required: true
          schema:
            type: string
            example: "wallet.statement"
            enum:
              - wallet.address_details
              - payout.proof_of_payout
              - wallet.statement
              - email.user.onboarding_confirmation_html
              - email.user.onboarding_confirmation_text
              - email.user.password_forgot_html
              - email.user.password_forgot_text
      responses:
        '200':
          description: OK
      security:
        - OAuth2:
            - admin
  /customization/templates/{templateName}/template:
    get:
      tags:
        - API Templates
      summary: Get Template
      description: Retrieve the currently configured template.
      operationId: getTemplate
      parameters:
      #- $ref: '#/components/parameters/Authorization'
      - name: templateName
        in: path
        description: The name of the Template.
        required: true
        schema:
          type: string
          example: "wallet.statement"
          enum:
            - wallet.address_details
            - wallet.balance_certificate
            - wallet.closure_certificate
            - wallet.confirmationLetter
            - wallet.domiciliation_certificate
            - payout.proof_of_payout
            - wallet.statement
            - email.user.onboarding_confirmation_html
            - email.user.onboarding_confirmation_text
            - email.user.password_forgot_html
            - email.user.password_forgot_text
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: The template file for the current configuration.
                properties:
                  template:
                    type: string
                    format: byte
                    description: The base64-encoded template.
                    example: "U29tZSBzYW1wbGUgdGV4dA=="
      security:
        - OAuth2:
            - admin
    put:
      tags:
        - API Templates
      summary: Upload Template
      description: Upload a replacement for an existing Template.
      operationId: putTemplateUpload
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: templateName
          in: path
          description: The name of the Template.
          required: true
          schema:
            type: string
            example: "wallet.statement"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                template:
                  type: string
                  format: byte
                  description: Your base64-encoded template.
                  example: "U29tZSBzYW1wbGUgdGV4dA=="
      responses:
        '201':
          description: Created
          content: {}
        '400':
          $ref: '#/components/responses/BadRequestError'
      security:
        - OAuth2:
          - admin
  /customization/templates/{templateName}/example:
    get:
      tags:
        - API Templates
      summary: Build Template Example
      description: Test your template by building one with dummy values.
      operationId: getTemplateExample
      parameters:
      #- $ref: '#/components/parameters/Authorization'
      - name: templateName
        in: path
        description: The name of the Template.
        required: true
        schema:
          type: string
          example: "wallet.statement"
          enum:
            - wallet.address_details
            - wallet.balance_certificate
            - wallet.closure_certificate
            - wallet.confirmationLetter
            - wallet.domiciliation_certificate
            - payout.proof_of_payout
            - wallet.statement
            - email.user.onboarding_confirmation_html
            - email.user.onboarding_confirmation_text
            - email.user.password_forgot_html
            - email.user.password_forgot_text
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  template:
                    type: string
                    format: byte
                    description: The base64-encoded template.
                    example: "U29tZSBzYW1wbGUgdGV4dA=="
      security:
        - OAuth2:
            - admin
  /core-connect/users/{userId}/kyc/document:
    get:
      tags:
        - User Document Pre-review
      summary: Search Pre-review Documents 
      description: | 
        Retrieve all pre-review documents for given user.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getKYCDocuments
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: userId
          in: path
          description: The unique identifier of the User.
          required: true
          schema:
            type: integer
            example: 12345
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    documentId:
                      type: string
                      format: uuid
                      description: |
                        The unique identifier of the pre-review document. This is different from the Id of the Document object.
                      example: "7f4a18e8-0a12-4822-af2e-d4b094085553"
                    documentType:
                      type: integer
                      description: | 
                        The `documentTypeId` of the file to upload. 
                        
                        See [Document types](/guide/user-verification/documents.html#types-documenttypeid) for the list of values.
                    status:
                      type: integer
                      description: |
                        Pre-review status of the document, which can be:
                        * `0` **Pending** – The document hasn't been pre-reviewed yet.
                        * `1` **Approved** – The document was refused during the pre-review.
                        * `2` **Rejected** – The document was validated during the pre-review. As a result, a Document object is created in the Treezor API.
                      enum: [0,1,2]
                    userId:
                      type: integer
                      description: The unique identifier of the user the document belongs to.
                    createdAt:
                      type: string
                      format: date-time
                      description: The date and time at which the pre-review document was created.
                      example: "2021-03-08T14:13:00.438Z"
                    metadata:
                      type: array
                      items:
                        type: string
                    comment:
                      type: string
                      description: Mandatory comment entered by your teams when pre-reviewing the document.
                      example: "The document meets the requirements"
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - read_only
    post:
      tags:
        - User Document Pre-review
      summary: Create Upload Document Form
      description: | 
        Generate a pre-signed form to upload documents for pre-review. Expires after 5 minutes.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getPreSignedKycForm
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: userId
          in: path
          description: The unique identifier of the User.
          required: true
          schema:
            type: string
            example: "12345"
      requestBody:
        content:
          application/json:
            schema:
              required:
                - documentType
              type: object
              properties:
                documentType:
                  type: integer
                  description: | 
                    The `documentTypeId` of the file to upload. 
                    
                    See [Document types](/guide/user-verification/documents.html#types-documenttypeid) for the list of values.
                metadata:
                  type: array
                  items:
                    type: string
                  description: Metadata to add to the document.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  documentId:
                    type: string
                    format: uuid
                    description: |
                      The unique identifier of the pre-review document. This is different from the Id of the Document object.
                    example: "7f4a18e8-0a12-4822-af2e-d4b094085553"
                  form:
                    type: object
                    properties:
                      action:
                        type: string
                        example: "https://sbx-connect-kyc-files.s3.eu-west-3.amazonaws.com"
                      method:
                        type: string
                        example: "POST"
                      enctype:
                        type: string
                        example: "multipart/form-data"
                  formFields:
                    type: object
                    properties:
                      acl:
                        type: string
                        example: "private"
                      key:
                        type: string
                        example: "1742230641_101619200_9_7f4a18e8-0a12-4822-af2e-d4b094085553_0"
                      Content-Type:
                        type: string
                        example: ""
                      X-Amz-Security-Token:
                        type: string
                      X-Amz-Credential:
                        type: string
                      X-Amz-Algorithm:
                        type: string
                        example: "AWS4-HMAC-SHA256"
                      X-Amz-Date:
                        type: string
                        example: "20250317T165721Z"
                      Policy:
                        type: string
                      X-Amz-Signature:
                        type: string
                  expireIn:
                    type: integer
                    description: The time after which the form expires in seconds.
                    example: 300
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - read_write
  /core-connect/kyc/documents/{documentId}/status:
    put:
      tags:
        - User Document Pre-review
      summary: Pre-review Document
      description: | 
        Update the pre-review status and comment of the document.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `legal` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: updateDocument
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: documentId
          in: path
          description: The unique identifier of the Document (UUID).
          required: true
          schema:
            type: string
            format: uuid
            example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      requestBody:
        content:
          application/json:
            schema:
              required:
                - status
                - comment
              type: object
              properties:
                status:
                  type: integer
                  description: |
                    Pre-review status of the document, which can be:
                    * `0` **Pending** – The document hasn't been pre-reviewed yet.
                    * `1` **Approved** – The document was refused during the pre-review.
                    * `2` **Rejected** – The document was validated during the pre-review. As a result, a Document object is created in the Treezor API.
                  enum: [0,1,2]
                comment:
                  type: string
                  description: The comment of the Document.
                  example: "The document meets the requirements"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  documentId:
                    type: string
                    format: uuid
                    description: |
                      The unique identifier of the pre-review document. This is different from the Id of the Document object.
                    example: "7f4a18e8-0a12-4822-af2e-d4b094085553"
                  documentType:
                    type: integer
                    description: | 
                      The `documentTypeId` of the file to upload. 
                      
                      See [Document types](/guide/user-verification/documents.html#types-documenttypeid) for the list of values.
                  status:
                    type: integer
                    description: |
                      Pre-review status of the document, which can be:
                      * `0` **Pending** – The document hasn't been pre-reviewed yet.
                      * `1` **Approved** – The document was refused during the pre-review.
                      * `2` **Rejected** – The document was validated during the pre-review. As a result, a Document object is created in the Treezor API.
                    enum: [0,1,2]
                  userId:
                    type: integer
                    description: The unique identifier of the user the document belongs to.
                  createdAt:
                    type: string
                    format: date-time
                    description: The date and time at which the pre-review document was created.
                    example: "2021-03-08T14:13:00.438Z"
                  updatedAt:
                    type: string
                    format: date-time
                    description: The date and time at which the pre-review document was updated.
                    example: "2021-03-10T12:11:05.438Z"
                  metadata:
                    type: array
                    items:
                      type: string
                  comment:
                    type: string
                    description: Mandatory comment entered by your teams when pre-reviewing the document.
                    example: "The document meets the requirements"
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - legal
  /core-connect/kyc/documents/{documentId}:
    delete:
      tags:
        - User Document Pre-review
      summary: Delete Pre-review Document 
      description: | 
        Delete a pre-review document.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `legal` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: deleteKYCDocumentcument
      parameters:
       #- $ref: '#/components/parameters/Authorization'
        - name: documentId
          in: path
          description: The unique identifier of the Document (UUID).
          required: true
          schema:
            type: string
            format: uuid
            example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  documentId:
                    type: string
                    format: uuid
                    description: |
                      The unique identifier of the pre-review document. This is different from the Id of the Document object.
                    example: "7f4a18e8-0a12-4822-af2e-d4b094085553"
                  documentType:
                    type: integer
                    description: | 
                      The `documentTypeId` of the file to upload. 
                      
                      See [Document types](/guide/user-verification/documents.html#types-documenttypeid) for the list of values.
                  status:
                    type: integer
                    enum: [0,1,2]
                  userId:
                    type: integer
                    description: The unique identifier of the user the document belongs to.
                  createdAt:
                    type: string
                    format: date-time
                    description: The date and time at which the pre-review document was created.
                    example: "2021-03-08T14:13:00.438Z"
                  updatedAt:
                    type: string
                    format: date-time
                    description: The date and time at which the pre-review document was updated.
                    example: "2021-03-10T12:11:05.438Z"
                  metadata:
                    type: array
                    items:
                      type: string
                  comment:
                    type: string
                    description: Mandatory comment entered by your teams when pre-reviewing the document.
                    example: "The document meets the requirements"
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - legal
  /core-connect/kyc/documents/{documentId}/preview:
    get:
      tags:
        - User Document Pre-review
      summary: Get Download URL
      description: | 
        Retrieve the pre-signed URL to download the pre-review document.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getPresignedUrlDocument
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: documentId
          in: path
          description: The unique identifier of the Document (UUID).
          required: true
          schema:
            type: string
            format: uuidƒac10b-58cc-4372-a567-0e02b2c3d479"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    description: The URL to view the document.
                    example: "https:\/\/yourcompany-kyc-files.s3.eu-west-3.amazonaws.com[...]"
                  contentType:
                    type: string
                    example: "image\/jpeg"
                  duration:
                    type: integer
                    description: The time for which the preview is available in seconds.
                    example: 300
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
  /core-connect/operations:
    get:
      tags:
        - Operations
      summary: Search Operations
      description: |
        Retrieve Operations that match your search conditions. The request must specify at least: `walletId`, `dateTo`, `dateFrom`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session for operations that are more than 90 days old. |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getOperations
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: query
          required: true
          description: The unique identifier of the card.
          schema:
            type: integer
            format: int64
            example: 12345
        - name: walletId
          in: query
          required: true
          description: The unique identifier of the Wallet.
          schema:
            type: integer
            format: int64
            example: 12345
        - name: dateFrom
          in: query
          required: true
          description: |
            The start of the period to take into account operations in RFC 339 date-time format (HTML encoded).
            The dates are to be html encoded (e.g., 2024-01-11T11:25:36+01:00 becomes `2024-01-11T11:25:36%2B01:00`)
          schema:
            type: string
            format: RFC 3339 date-time
            example: "2025-04-18T11:00:00%2B01:00"
        - name: dateTo
          in: query
          required: true
          description: | 
            The end of the period to take into account operations in RFC 339 date-time format (HTML encoded).
            The dates are to be html encoded (e.g., 2024-01-11T11:25:36+01:00 becomes `2024-01-11T11:25:36%2B01:00`)
          schema:
            type: string
            format: RFC 3339 date-time
            example: "2025-04-18T11:00:00%2B01:00"
        - name: pageSize
          in: query
          description: Number of results per page
          schema:
            type: integer
            format: int64
            minimum: 1
            maximum: 100
            default: 15
        - name: operationType
          in: query
          description: |
            The type of operation. Can't be cumulated with other query parameters. 

            By default, Treezor returns all operation types when this field isn't defined.
          schema:
            type: array
            items:
              type: string
              enum:
                - bankDirectDebit
                - bankTransfer
                - cardTopup
                - cardTransaction
                - check
                - creditNote
                - fees
                - intBankTransfer
                - instantBankTransfer
                - other
                - payinRefund
                - payoutRefund
                - transferRefund
                - walletTransfer
        - name: cursor
          in: query
          description: |
            Pagination cursor, if you don't pass a cursor, result will start at the first page.
          schema:
            type: string
            example: "da4b9237bacccdf19c0760cab7aec4a8359010b0"
        -   name: initialFlow
            in: query
            description: Technical context about the initial operation. Can't be cumulated with other query parameters.
            schema:
              type: array
              nullable: true
              items:
                type: string
                enum:
                  - cardTransaction
                  - chargeback
                  - payin
                  - payinRefund
                  - payout
                  - payoutRefund
                  - transfer
        -   name: direction
            in: query
            description: Direction of the operation.
            schema:
              type: string
              nullable: true
              enum:
                - CREDIT
                - DEBIT
        -   name: amountFrom
            in: query
            description: The minimum amount of the operations to take into account.
            schema:
              type: integer
              nullable: true
        -   name: amountTo
            in: query
            description: The maximum amount of the operations to take into account.
            schema:
              type: string
        -   name: status
            in: query
            description: The status of the operation.
            schema:
              type: array
              items:
                type: string
                enum:
                  - 'AUTHORIZED'
                  - 'CANCELED'
                  - 'DECLINED'
                  - 'SETTLED'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        operationType:
                          type: string
                          enum:
                            - bankDirectDebit
                            - bankTransfer
                            - cardTopup
                            - cardTransaction
                            - check
                            - creditNote
                            - fees
                            - intBankTransfer
                            - instantBankTransfer
                            - other
                            - payinRefund
                            - payoutRefund
                            - transferRefund
                            - walletTransfer
                          description: |
                            Type of operation.
                          example: cardTransaction
                        amount:
                          type: object
                          properties:
                            amount:
                              type: integer
                              description: Amount in cent
                              example: 32420
                            currency:
                              type: string
                              description: Currency in ISO (EUR, GBP etc.)
                              example: EUR
                        status:
                          type: string
                          enum:
                            - AUTHORIZED
                            - CANCELED
                            - DECLINED
                            - SETTLED
                          description: operation status
                        walletId:
                          type: integer
                          format: int64
                          description: ID of the wallet impacted
                        direction:
                          type: string
                          enum:
                            - CREDIT
                            - DEBIT
                          description: Direction of operation credit or debit
                        objectId:
                          type: integer
                          format: int64
                          description: |
                            The unique identifier of the Treezor object that contains the initial operation.

                            For card transactions, this is the `paymentId`. Use `/v1/cardtransactions` with the `paymentId` query parameter to retrieve the associated card transactions.
                        label:
                          type: string
                          nullable: true
                          description: The tag attached to the operation
                        metadata:
                          type: object
                          oneOf:
                            -   $ref: '#/components/schemas/CardPayment'
                            -   $ref: '#/components/schemas/Chargeback'
                            -   $ref: '#/components/schemas/Payin'
                            -   $ref: '#/components/schemas/PayinRefund'
                            -   $ref: '#/components/schemas/Payout'
                            -   $ref: '#/components/schemas/PayoutRefund'
                            -   $ref: '#/components/schemas/Transfer'
                        date:
                          type: object
                          properties:
                            creation:
                              type: string
                              format: date-time
                              description: |
                                Date and time at which the payin/payout/cardtransaction object was created in Treezor systems.
                              example: "2024-02-07T08:04:48+01:00"
                            settlement:
                              type: string
                              format: date-time
                              nullable: true
                              description: |
                                Date and time at which the operation is settled on the wallet.
                              example: "2024-02-07T08:04:48+01:00"
                        initialFlow:
                          description: Context about the technical context of the initial operation.
                          type: string
                          enum:
                            - cardTransaction
                            - chargeback
                            - payin
                            - payinRefund
                            - payout
                            - payoutRefund
                            - transfer
                        transactionId:
                          type: string
                          nullable: true
                          description: |
                            The unique identifier of the Transaction associated with this operation.

                            Returns `null` when the operation `status` is not `SETTLED`.
                          example: "7644931"
                  cursor:
                    type: object
                    properties:
                      prev:
                        type: string
                        nullable: true
                        description: |
                          Pointer value for previous page. Set to `null` when on the first page.
                        example: "356a192b7913b04c54574d18c28d46e6395428ab"
                      current:
                        type: string
                        nullable: true
                        description: |
                          Pointer for the current page.
                        example: "da4b9237bacccdf19c0760cab7aec4a8359010b0"
                      next:
                        type: string
                        nullable: true
                        description: |
                          Pointer value for next page. Set to `null` when on the first page.
                        example: "da4b9237bacccdf19c0760cab7aec4a8359010b0"
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
  /core-connect/sca/scawallets:
    get:
      tags:
        - SCA
      summary: Search SCA Wallets
      description: | 
        Retrieve the list of [SCA Wallets](/guide/strong-customer-authentication/introduction.html#sca-wallet-object) for a given user.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getSCAWallets
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - in: query
          name: userId
          description: The unique identifier of the user.
          required: true
          schema:
            type: string
            example: "123456"
        - in: query
          name: cursor
          description: Pagination cursor, if you don't pass a cursor, result will start at the first page.
          schema:
            type: string
            example: "da4b9237bacccdf19c0760cab7aec4a8359010b0"
        - in: query
          name: status
          description: The status of SCA Wallet.
          schema:
            type: string
            enum:
              - ACTIVE
              - CREATED
              - CREATING
              - DELETED
              - INITIALIZING
      responses:
        '200':
          description: The list of wallet was successfully retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  scaWallets:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: The unique identifier of the SCA Wallet.
                          example: "310a488efab74ba2bc699b4f841b0bc4"
                        status:
                          type: string
                          description: The status of the SCA Wallet.
                          enum:
                            - ACTIVE
                            - CREATED
                            - CREATING
                            - DELETED
                            - INITIALIZING
                          nullable: true
                        subStatus:
                          type: string
                          enum:
                            - CREATING_IN_PROGRESS
                            - CREATED_BLOCKED
                            - CREATED_READY
                            - INITIALIZING_MOBILE
                            - ACTIVATED_LOGGED_IN
                            - ACTIVATED_LOGGED_OUT
                            - DELETED_BY_ISSUER
                            - DELETED_UNINSTALLED
                          nullable: true
                        passcodeStatus:
                          type: string
                          enum:
                            - NONE
                            - NOT_SET
                            - SET
                            - TO_BE_CHANGED
                          nullable: true
                        locked:
                          type: boolean
                          nullable: true
                        lockReasons:
                          type: array
                          items:
                            type: string
                            enum:
                              - FRAUDULENT_USE_SUSPECTED_BY_CLIENT
                              - FRAUDULENT_USE_SUSPECTED_BY_ISSUER
                              - ISSUER
                              - LOST_DEVICE
                              - STOLEN_DEVICE
                              - TERMINATE_SERVICE
                          nullable: true
                        lockMessage:
                          type: string
                          nullable: true
                          example: "Deleted"
                        settingsProfile:
                          type: string
                          nullable: true
                          enum:
                            - default
                            - webauthn
                        mobileWallet:
                          type: object
                          properties:
                            appBuildNumber:
                              type: string
                              example: "v04-04-06-06-02-02"
                            sdkVersion:
                              type: string
                              example: "2.4.11"
                            os:
                              type: string
                              example: "ANDROID"
                            osVersion:
                              type: string
                              example: "13"
                            brand:
                              type: string
                              example: "samsung"
                            productModel:
                              type: string
                              example: "SM-A226B"
                            deviceId:
                              type: string
                              example: "0097e609be9335cc"
                            deviceIdType:
                              type: string
                              example: "ANDROID_ID"
                            productFingerprint:
                              type: string
                              example: "samsung/a45xnseea/a22x:13/TP1A.220924.014/A2200XXU5DWC1:user/release-keys"
                            secretFingerprint:
                              type: string
                              example: "0x1754726a90d3664350f8118047b1482d7c17d521f466da772a09b5be2cc67eaa"
                            root:
                              type: string
                              example: "0"
                            pushMessagingId:
                              type: string
                              example: "fTUGDWeXQnW4fgTBvpKvWo:APA91bEevu80iZJm3_59UYDQAiBiJYoASQ2TZfGgCwmCziPqe_ipnh3ZEFV5tGzPN3JpXjO4xRFA-Kmy3JEjgPO1mPPk6WxjEWcyDIiM33DkTOsvGxekG7f5d1xh4YAz6BQLLHkp0usC"
                            pushMessagingProvider:
                              type: string
                              example: "FIREBASE"
                            mobileUpdateDate:
                              type: string
                              format: date-time
                              example: "2024-05-03T09:43:15Z"
                            lastEligibilityCheck:
                              type: string
                              format: date-time
                              example: "2024-05-03T09:43:15Z"
                            nfc:
                              type: boolean
                            emulator:
                              type: boolean
                            appleTeamId:
                              type: string
                              example: "567890"
                        activationCode:
                          type: string
                          description: The code to authenticate the end user (mobile provisioning).
                        creationDate:
                          type: string
                          format: date-time
                          description: The date and time at which the SCA Wallet was created.
                          nullable: true
                          example: "2024-05-30T16:09:22+02:00"
                        deletionDate:
                          type: string
                          format: date-time
                          description: The date and time at which the SCA Wallet was deleted.
                          nullable: true
                          example: "2024-05-30T16:09:22+02:00"
                        activationCodeExpiryDate:
                          type: string
                          format: date-time
                          description: |
                            The date and time before which the `activationCode` must be use for mobile provisioning.
                          nullable: true
                          example: "2024-05-30T16:29:22+02:00"
                        authenticationMethods:
                          type: array
                          oneOf:
                            - $ref: '#/components/schemas/EntrustAuthenticationMethods'
                            - $ref: '#/components/schemas/WebAuthnAuthenticationMethods'
                          items:
                            type: object
                          nullable: true
                        invalidActivationAttempts:
                          type: string
                          nullable: true
                        userId:
                          type: string
                          nullable: true
                          description: The unique identifier of the user who owns the SCA Wallet.
                          example: "4567890"
                        scaWalletTag:
                          type: string
                          nullable: true
                          maxLength: 256
                          description: |
                            Custom value for the SCA Wallet. Can be used to name the device for which the new SCA Wallet is created. 
                        clientId:
                          type: string
                          description: The identifier of the environment the SCA Wallet belongs to.
                          example: "12345"
                        activationDate:
                          type: string
                          format: date-time
                          nullable: true
                          description: The date and time at which the SCA Wallet was activated.
                          example: "2025-03-21T11:46:00+01:00"
                        lockDate:
                          type: string
                          format: date-time
                          description: | 
                            The date and time at which the SCA Wallet was locked.
                          nullable: true
                          example: "2025-03-21T11:46:00+01:00"
                        unlockDate:
                          type: string
                          format: date-time
                          description: | 
                            The date and time at which the SCA Wallet was unlocked.
                          nullable: true
                          example: "2025-03-21T11:46:00+01:00"
                        resetPinDate:
                          type: string
                          format: date-time
                          description: | 
                            The date and time at which the SCA Wallet PIN was reset.
                          nullable: true
                          example: "2025-03-21T11:46:00+01:00"
                  cursor:
                    type: object
                    properties:
                      prev:
                        type: string
                        nullable: true
                        description: |
                          Pointer value for previous page. Set to `null` when on the first page.
                        example: "356a192b7913b04c54574d18c28d46e6395428ab"
                      current:
                        type: string
                        nullable: true
                        description: |
                          Pointer for the current page.
                        example: "da4b9237bacccdf19c0760cab7aec4a8359010b0"
                      next:
                        type: string
                        nullable: true
                        description: |
                          Pointer value for next page. Set to `null` when on the first page.
                        example: "da4b9237bacccdf19c0760cab7aec4a8359010b0"
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
    post:
      tags:
        - SCA
      summary: Create SCA Wallet
      operationId: postScaWallet
      description: |
        Create a new [SCA Wallet](/guide/strong-customer-authentication/introduction.html#sca-wallet-object) manually.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write`, `legal` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`sca.wallet.create`](/guide/strong-customer-authentication/events.html#sca-wallet-create) |
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - userId
              type: object
              properties:
                userId:
                  type: string
                  description: The unique identifier of the User.
                scaWalletTag:
                  type: string
                  maxLength: 256
                  description: |
                    Custom value for the SCA Wallet. Can be used to name the device for which the new SCA Wallet is created. 
                  nullable: true
                authMethod:
                  type: array
                  description: The chosen methods for the 2-factor authentication.
                  items:
                    type: string
                    enum:
                      - "ID"
                      - "OTHER"
                      - "OTP EMAIL"
                      - "OTP SMS"
      responses:
        '200':
          description: The wallet was successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScaWalletObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /core-connect/sca/scawallets/swap:
    post:
      tags:
        - SCA
      summary: Swap SCA Wallets
      description: |
        Create an SCA Wallet while deleting the previous one as users should have only one device enrolled.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`sca.wallet.swap`](/guide/strong-customer-authentication/events.html#sca-wallet-swap) |
      operationId: swapSCAWallets
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - removeScaWalletId
                - swapReason
              type: object
              properties:
                removeScaWalletId:
                  type: string
                  description: The unique identifier of the SCA Wallet to be deleted.
                swapReason:
                  type: string
                  description: The reason for swapping SCA Wallet.
                  enum:
                    - LOST
                    - OTHER
                    - STOLEN
                authMethod:
                  type: array
                  description: | 
                    The chosen methods for the 2-factor authentication. Required if no `scaProof` is provided.
                  items:
                    type: string
                    enum:
                      - ID
                      - OTHER
                      - OTP SMS
                      - OTP EMAIL
                sca:
                  type: string
                  description: The valid proof that authenticated the swap. Required if no `authMethod` is provided.
                scaWalletTag:
                  type: string
                  maxLength: 256
                  description: |
                    Custom value for the SCA Wallet. Can be used to name the device for which the new SCA Wallet is created. 
      responses:
        '200':
          description: The list of wallet was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScaWalletObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /core-connect/sca/scawallets/{scaWalletId}:
    parameters:
      - in: path
        name: scaWalletId
        required: true
        description: The unique identifier of the SCA Wallet.
        schema:
          type: string
          example: "12345"
    delete:
      tags:
        - SCA
      summary: Delete SCA Wallet
      operationId: deleteScaWallet
      description: |
        Permanently delete an SCA Wallet.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`sca.wallet.delete`](/guide/strong-customer-authentication/events.html#sca-wallet-delete) |
      #parameters:
      #- $ref: '#/components/parameters/Authorization'
      responses:
        '200':
          description: The wallet was successfully deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScaWalletObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
    get:
      tags:
        - SCA
      summary: Get SCA Wallet
      description: | 
        Retrieve an SCA Wallet by providing its `id`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getScaWallet
     # parameters:
        #- $ref: '#/components/parameters/Authorization'
      responses:
        '200':
          description: The wallet was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScaWalletObject'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
  /core-connect/sca/scawallets/{scaWalletId}/lock:
    parameters:
      - in: path
        name: scaWalletId
        required: true
        description: The unique identifier of the SCA Wallet.
        schema:
          type: string
          example: "12345"
    put:
      tags:
        - SCA
      summary: Lock SCA Wallet
      operationId: putScaWallet
      description: |
        Locks an SCA Wallet so that none of the services it offers can be unlocked until it is unlocked.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`sca.wallet.lock`](/guide/strong-customer-authentication/events.html#sca-wallet-lock) |
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - lockReason
              type: object
              properties:
                lockReason:
                  type: string
                  description: The reason for locking the Wallet.
                  enum:
                    - DELETED
                    - FRAUDULENT_USE_SUSPECTED_BY_CLIENT
                    - FRAUDULENT_USE_SUSPECTED_BY_ISSUER
                    - ISSUER
                    - LOST_DEVICE
                    - STOLEN_DEVICE
                    - TERMINATE_SERVICE
                lockMessage:
                  type: string
                  nullable: true
                  description: The details regarding why the SCA Wallet is locked.
                authMethod:
                  type: array
                  description: |
                    The chosen methods for the 2-factor authentication. Required if no `scaProof` is provided.
                  items:
                    type: string
                    enum:
                      - ID
                      - OTHER
                      - OTP SMS
                      - OTP EMAIL
                sca:
                  type: string
                  description: The valid proof that authenticated the swap. Required if no `authMethod` is provided.
      responses:
        '200':
          description: The wallet is locked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScaWalletObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /core-connect/sca/scawallets/{scaWalletId}/unlock:
    parameters:
      - in: path
        name: scaWalletId
        required: true
        description: The unique identifier of the SCA Wallet.
        schema:
          type: string
          example: "12345"
    put:
      tags:
        - SCA
      summary: Unlock SCA Wallet
      description: |
        Unlock an SCA Wallet.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-operation |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`sca.wallet.unlock`](/guide/strong-customer-authentication/events.html#sca-wallet-unlock) |
      operationId: unlockScaWallet
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                authMethod:
                  type: array
                  description: |
                    The chosen methods for the 2-factor authentication. Required if no `scaProof` is provided.
                  items:
                    type: string
                    enum:
                      - ID
                      - OTHER
                      - OTP SMS
                      - OTP EMAIL
                sca:
                  type: string
                  description: The valid proof that authenticated the swap. Required if no `authMethod` is provided.
      responses:
        '200':
          description: The wallet is unlocked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScaWalletObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /core-connect/sca/scawallets/{scaWalletId}/resetPin:
    parameters:
      - in: path
        name: scaWalletId
        required: true
        description: The unique identifier of the SCA Wallet.
        schema:
          type: string
          example: "12345"
    put:
      tags:
        - SCA
      summary: Reset PIN
      operationId: resetScaWalletPin
      description: |
        Reset the PIN code of an SCA Wallet if the user has locked their Wallet after too many consecutive wrong PIN attempts. See [Reset PIN (Mobile)](/guide/strong-customer-authentication/sca-wallet-lifecycle.html#reset-pin-mobile) for more information.
        
        Once the PIN reset, the Customer can set a new PIN via the mobile application.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `legal` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-operation for mobile wallets only |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`sca.wallet.resetPin`](/guide/strong-customer-authentication/events.html#sca-wallet-resetpin) |
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      responses:
        '200':
          description: PIN has been reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScaWalletObject'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - legal
  /core-connect/sca/setPasscode:
    put:
      summary: Change Passcode
      description: |
        Change the passcode ([Web Native SCA](/guide/strong-customer-authentication/introduction.html#web-native)).

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per operation, for web native wallets only |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: setPasscode
      tags:
        - SCA
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                  description: The unique identifier of the user.
                newPasscode:
                  type: string
                  description: The new passcode. Must be base64 encoded and encrypted. Initial passcode must at least 6 characters.
                confirmPasscode:
                  type: string
                  description: Confirmation of the new passcode.
                sca:
                  type: string
                  description: The valid proof that authenticated the user. Required if no `authMethod` is provided.
                authMethod:
                  type: array
                  description: | 
                    The chosen methods for the 2-factor authentication. Required if no `sca` is provided.
                  items:
                    type: string
                    enum:
                      - ID
                      - OTHER
                      - OTP SMS
                      - OTP EMAIL
      responses:
        '204':
          description: Accepted
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /simulation/scaProof:
    post:
      tags: 
        - SCA Proof Simulation
      summary: Simulate SCA Proof
      description: | 
        Create an `scaProof` for testing SCA authentication flows without a dedicated front end. Use the `scaProof` to secure end user flow with a `delegated_end_user` JWT in `sandbox`. 
        
        See the [Simulate SCA Proof](/guide/strong-customer-authentication/faking-operations.html#simulate-sca-proof) article for more information.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `admin` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: postScaProof
      #parameters: 
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content: 
          application/json:
            schema:
              required:
                - scaWalletId
              type: object
              properties:
                scaWalletId:
                  type: string
                  description : |
                    The unique identifier of the SCA Wallet from which the scaProof is to be created.
                url:
                  type: string
                  description : |
                    The URL of the endpoint for which the sensitive action is to be secured with an SCA.
                body:
                  type: object
                  description : |
                    Data to sign in the SCA proof body. 
                    
                    See the [Per Operation](/guide/strong-customer-authentication/securing-endpoints.html#per-operation) table to know which data to sign for each endpoint.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  scaProof:
                    type: string
                    description: The `scaProof` to use for SCA authentication in `Sandbox`.
                    example: "eyJh_NDN9.WQBp_Xg7w"
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - admin
  /core-connect/sca/externalOperations:
    post:
      summary: Create External Operation declaration
      description: |
        Declare an SCA External Operation (i.e., a sensitive action that was made outside of Treezor services).

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: postExtOperation
      tags:
        - SCA External Operations
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - actionName
              properties:
                actionName:
                  type: string
                  description: | 
                    The end user action that was secured by an SCA. See [list of actions](/guide/strong-customer-authentication/securing-endpoints.html#action-names-actionname) for more information.
                  enum:
                    - externalDisplayAccountDetails
                    - externalGetBalance
                    - externalGetStatement
                    - externalMassPayoutOrderCreation
                    - externalMassTransferOrderCreation
                    - externalOperationView
                    - externalOperationView90Days
                    - externalScheduledPayoutOrder
                    - externalScheduledTransferOrder
                    - externalUpdateLimitsCard
                    - internalCheck
                scaProof:
                  type: string
                  description: | 
                    The valid proof that authenticated the end user's action. Required if `actionName` is covered by a per-operation SCA.
                  nullable: true
                  example: "eyJh_NDN9.WQBp_Xg7w"
                actionDate:
                  type: string
                  description: | 
                    The date on which the declared action took place. (Format: RFC3339).
                  format: date-time
                  example: "2023-06-20T01:02:03+01:00"
                resourceIds:
                  type: array
                  items:
                    type: string
                    example: "12345"
                  description: | 
                    The list of unique identifiers (strings) of the objects, conditioned by the type of action. Must be: 
                    * **walletId** for `externalGetStatement`, `externalGetBalance`, `externalOperationView`, `externalOperationView90Days`, and `externalDisplayAccountDetails`
                    * **payoutId** for **transferId** in case of a payout or transfer
                    * **cardId** for `externalUpdateLimitsCard`
                  nullable: true
      responses:
        '201':
          description: The External Operation was successfully created.
          content:
            application/json:
              schema:
                properties:
                  ExternalOperation:
                    type: object
                    properties:
                      externalOperationId:
                        type: string
                        format: uuid
                        description: The unique identifier (uiid) of the ExternalOperation.
                        example: '538643ab-7c76-4e53-a32a-f378f781e394'
                      actionName:
                        type: string
                        description: The end user action that was secured by an SCA.
                        example: 'externalOperationView'
                      scaProof:
                        type: string
                        nullable: true
                        description: The valid proof that authenticated the end user's action.
                        example: "eyJh_NDN9.WQBp_Xg7w"
                      actionDate:
                        type: string
                        description: The date on which the declared action took place.
                        example: "2023-06-20T11:01:03+01:00"
                      resourceIds:
                        type: array
                        items:
                          type: string
                        nullable: true
                        description: The list of unique identifiers (strings) of the objects in case of a payout or transfer.
                      createdAt:
                        type: string
                        format: date-time
                        description: | 
                          The date and time at which the External Operation was created. (Format: RFC 3339)
                        nullable: true
                        example: "2023-06-20T11:02:03+01:00"
                      scaDate:
                        type: string
                        format: date-time
                        description: | 
                          The `iat` timestamp of the `scaProof` for per-operation SCA.
                        nullable: true
                        example: "2023-06-20T11:01:13+01:00"
                      amr:
                        type: string
                        description: The type of SCA for per-operation SCA
                        enum: [CLOUD_PIN, DEVICE_BIOMETRIC, HYBRID_PIN]
                        nullable: true
                      externalOperationNote:
                        type: string
                        description: | 
                          Comment left by Treezor after scoring, indicating a potential issue. See [List of notes](/guide/strong-customer-authentication/securing-endpoints.html#notes-externaloperationnote)
                        example: 'Wrong JWT. Grant type must be delegated end user'
                        nullable: true
                      externalOperationResponseCode:
                        type: integer
                        description: For Treezor purposes only.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /core-connect/sca/externalOperations/{externalOperationId}:
    put:
      summary: Update External Operation declaration
      description: | 
        Modify an SCA External Operation declaration. 
        
        This feature is only available for Per Operation operations, in other words for external operations whose action name is: `externalMassPayoutOrderCreation`, 
        `externalMassTransferOrderCreation`, `externalScheduledPayoutOrder`, or `externalScheduledTransferOrder`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: putExtOperation
      tags:
        - SCA External Operations
      parameters:
       #- $ref: '#/components/parameters/Authorization'
        - name: externalOperationId
          in: path
          description: The unique identifier (uiid) of the ExternalOperation.
          required: true
          schema:
            type: string
            format: uuid
            example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - resourceIds
              properties:
                resourceIds:
                  type: array
                  items:
                    type: string
                    example: "538643ab-7c76-4e53-a32a-f378f781e394"
                  description: The list of unique identifiers (strings) of the objects in case of a payout or transfer. Must be null/empty for [externalGetBalance, externalOperationView, externalOperationView90Days, externalDisplayAccountDetails, externalGetStatement]
                  nullable: true
      responses:
        '200':
          description: The External Operation was successfully updated.
          content:
            application/json:
              schema:
                properties:
                  ExternalOperation:
                    type: object
                    properties:
                      externalOperationId:
                        type: string
                        format: uuid
                        description: The unique identifier (uiid) of the ExternalOperation.
                        example: '538643ab-7c76-4e53-a32a-f378f781e394'
                      actionName:
                        type: string
                        description: The end user action that was secured by an SCA.
                        example: 'externalOperationView'
                      scaProof:
                        type: string
                        nullable: true
                        description: The valid proof that authenticated the end user's action.
                        example: "eyJh_NDN9.WQBp_Xg7w"
                      actionDate:
                        type: string
                        description: The date on which the declared action took place.
                        example: "2023-06-20T11:01:03+01:00"
                      resourceIds:
                        type: array
                        items:
                          type: string
                        nullable: true
                        description: The list of unique identifiers (strings) of the objects in case of a payout or transfer.
                      createdAt:
                        type: string
                        format: date-time
                        description: | 
                          The date and time at which the External Operation was created. (Format: RFC 3339)
                        nullable: true
                        example: "2023-06-20T11:02:03+01:00"
                      scaDate:
                        type: string
                        format: date-time
                        description: | 
                          The `iat` timestamp of the `scaProof` for per-operation SCA.
                        nullable: true
                        example: "2023-06-20T11:01:13+01:00"
                      amr:
                        type: string
                        description: The type of SCA for per-operation SCA
                        enum: [CLOUD_PIN, DEVICE_BIOMETRIC, HYBRID_PIN]
                        nullable: true
                      externalOperationNote:
                        type: string
                        description: | 
                          Comment left by Treezor after scoring, indicating a potential issue. See [List of notes](/guide/strong-customer-authentication/securing-endpoints.html#notes-externaloperationnote)
                        nullable: true
                        example: 'Declaration delay is too long'
                      externalOperationResponseCode:
                        type: integer
                        description: For Treezor purposes only.
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /core-connect/statements/{walletId}/raw:
    get:
      tags:
          - Account Documents
      summary: Get JSON Account Statement
      description: | 
        Retrieve the raw data (json) to build a Wallet account statement.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getRawStatement
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: walletId
          in: path
          description: The unique identifier of the Wallet.
          required: true
          schema:
            type: string
            example: "12345"
        - name: month
          in: query
          description: The month of the statement (2 digits, e.g., `02`)
          required: true
          schema:
            type: integer
            example: 02
        - name: year
          in: query
          description: The year of the statement (4 digits, e.g., `2025`)
          required: true
          schema:
            type: integer
            example: 2025
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: The raw account statement object.
                properties:
                  firstBalance:
                    type: object
                    properties:
                      amount:
                        type: string
                        format: float
                        example: "5.76"
                      date:
                        type: string
                        format: date
                        example: "2025-03-01"
                  lastBalance:
                    type: object
                    properties:
                      amount:
                        type: string
                        format: float
                        example: "-553.03"
                      date:
                        type: string
                        format: date
                        example: "2025-03-31"
                  operations:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          example: "2022-01-31"
                        type:
                          type: string
                          example: "Vir SEPA"
                          enum:
                            - Chèque
                            - Credit note
                            - Frais
                            - Prlv SEPA
                            - Prlv SEPA B2B
                            - Remb Chèque
                            - Remb Prlv SEPA
                            - Remb Prlv SEPA B2B
                            - Remb Top up carte
                            - Remb Vir SEPA
                            - Top up carte
                            - Vir Int
                            - Vir SEPA
                            - Virement
                        name:
                          type: string
                          example: "Reece Little (978 46.81)"
                        direction:
                          type: string
                          example: "DEBIT"
                          enum:
                            - CREDIT
                            - DEBIT
                        amount:
                          type: string
                          format: float
                          example: "97.34"
                        walletBalance:
                          type: string
                          format: float
                          example: "1123.98"
                          description: The running balance of the wallet for each operation.
                        metadata:
                          type: object
                          description: | 
                            Additional information regarding the operation. Content depends on the `type`.
                          oneOf:
                          - $ref: '#/components/schemas/statementCardPayment'
                          - $ref: '#/components/schemas/statementPayin'
                          - $ref: '#/components/schemas/statementPayinRefund'
                          - $ref: '#/components/schemas/statementPayout'
                          - $ref: '#/components/schemas/statementPayoutRefund'
                          - $ref: '#/components/schemas/statementTransfer'
                  totalDebit:
                    type: string
                    example: "0.00"
                  totalCredit:
                    type: string
                    example: "0.00"
                  user:
                    type: object
                    properties:
                      title:
                        type: string
                        enum:
                          - M
                          - MLLE
                          - MME
                          - MX
                        example: "M"
                      firstname:
                        type: string
                        example: "Alex"
                      lastname:
                        type: string
                        example: "Oak"
                      address1:
                        type: string
                        example: "15 Rosewood Road"
                      address2:
                        type: string
                      address3:
                        type: string
                        nullable: true
                      postcode:
                        type: string
                        example: "75014"
                      city:
                        type: string
                        example: "Paris"
                      country:
                        type: string
                        example: "FR"
                      userTypeId:
                        type: integer
                      state:
                        type: string
                      legalName:
                        type: string
                      legalRegistrationNumber:
                        type: string
                  wallet:
                    type: object
                    properties:
                      iban:
                        type: string
                        example: "FR761679800001000012345678"
                      bic:
                        type: string
                        example: "TRZOFR21XXX"
                  totalAmountFees:
                    type: number
                    format: float
                    example: 0
                  totalAmountCreditNote:
                    type: number
                    format: float
                    example: 0
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
  /core-connect/statements/{walletId}/computed:
    get:
      tags:
          - Account Documents
      summary: Get PDF Account Statement
      description: | 
        Retrieve a Wallet account statement in pdf format.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getPdfAccountStatement
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: walletId
          in: path
          description: The unique identifier of the Wallet.
          required: true
          schema:
            type: string
            example: "12345"
        - name: month
          in: query
          description: The month of the statement (2 digits leading with `0`).
          required: true
          schema:
            type: integer
            example: 11
        - name: year
          in: query
          description: The year of the statement (4 digits).
          required: true
          schema:
            type: integer
            example: 2024
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: The PDF account statement to download.
                properties:
                  link:
                    type: string
                    description: The URL to download the PDF file.
                    example: https://xxx.s3.eu-west-3.amazonaws.com/tmp/xxx.pdf
                  expireIn:
                    type: integer
                    description: The time after which the download link expires (in seconds).
                    default: 300
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
  /v1/balances:
    get:
      tags:
        - Balances
      summary: Search Balances
      description: | 
        Retrieve Balances for a given `walletId` or `userId`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session with 180 days exemption |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getBalances
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: walletId
          in: query
          description: The unique identifier of the Wallet whose Balance is to be retrieved.
          schema:
            type: integer
            example: 12345
        - name: userId
          in: query
          description: The unique identifier of the User whose Wallet Balances are to be retrieved.
          schema:
            type: integer
            example: 12345
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  balances:
                    type: array
                    items:
                      type: object
                      properties:
                        walletId:
                          type: integer
                          description: The unique identifier of the Wallet.
                          example: 12345
                        currentBalance:
                          type: number
                          format: float
                          description: |
                            The amount of money currently available on the wallet without considering pending operations. 

                            See [Balance](/guide/wallets/balances.html) article for more information.
                          example: 500.28
                        authorizations:
                          type: number
                          format: float
                          description: |
                            The pending operations amount.

                            See [Balance](/guide/wallets/balances.html) article for more information.
                          example: 100.25
                        authorizedBalance:
                          type: number
                          format: float
                          description: |
                            The simulated balance, which amount takes into account pending operations (i.e., authorizations amount is deducted from the balance).

                            See [Balance](/guide/wallets/balances.html) article for more information.
                          example: 400.03
                        currency:
                          type: string
                          format: ISO 4217
                          description: |
                            The currency of the Wallet in [ISO 4217](/guide/api-basics/data-format.html#currencies) format.
                          example: "EUR"
                        calculationDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: | 
                            The date and time at which the balance was last calculated. Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2025-01-09 11:46:44"
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
  /v1/beneficiaries:
    get:
      tags:
        - Beneficiaries
      summary: Search Beneficiaries
      description: | 
        Retrieve Beneficiary bank accounts that match search criteria.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A|
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getBeneficiaries
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: fields
          in: query
          description: List of the object properties to be returned, allowing you to filter the response payload.
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: filter
          in: query
          description: |
            You can filter the API response by using filter(s).

            Filterable fields are:
             - id
             - tag
             - userId
             - isActive (1 for yes, 0 for no)
             - nickName
             - address
             - iban (encrypted IBAN)
             - IbanInClear
             - bic
             - sepaCreditorIdentifier
             - usableForSct
             - createdDate
             - modifiedDate

            Filters should be separated by a ";". Example for 3 filters:
            FILTER1;FILTER2;FILTER3.

            A single filter has the following syntax : "fieldName criterion expression".

            Where:
             - fieldName: the name of a filterable field of this object.
             - expression: the values to be included or excluded (see the table below for more information)
             - criterion: a filter criterion.

            Here are the possible values for criterion:

             | Criteria |         Description    |                   Type                   | Expression Example |
             |----------|------------------------|------------------------------------------|--------------------|
             |     >    |      greater than      |            alphanumeric string           |         100        |
             |    >=    | greater or equal than  |            alphanumeric string           |         100        |
             |     <    |        less than       |            alphanumeric string           |         100        |
             |    <=    |   less or equal than   |            alphanumeric string           |         100        |
             |    !=    |      not equal to      |            alphanumeric string           |         100        |
             |   like   |          like          |            alphanumeric string           |         100        |
             |    in    |           in           | alphanumeric strings separated by commas |      100,30,25     |
             |    ==    |         equals         |            alphanumeric string           |         100        |
          schema:
            type: string
        - name: id
          in: query
          description: The unique identifier of the Beneficiary.
          schema:
            type: integer
            example: 12345
        # - name: userId
        #   deprecated: true
        #   in: query
        #   description: Deprecated, use the `filter` parameter instead.
        #   schema:
        #     type: integer
        # - name: iban
        #   deprecated: true
        #   in: query
        #   description: Deprecated, use the `filter` parameter instead.
        #   schema:
        #     type: string
        # - name: bic
        #   deprecated: true
        #   in: query
        #   description: Deprecated, use the `filter` parameter instead.
        #   schema:
        #     type: string
        # - name: nickName
        #   deprecated: true
        #   in: query
        #   description: Deprecated, use the `filter` parameter instead.
        #   schema:
        #     type: string
        # - name: name
        #   deprecated: true
        #   in: query
        #   description: Deprecated, use the `filter` parameter instead.
        #   schema:
        #     type: string
        - name: pageNumber
          in: query
          description: |
            The page number, only available on /v1/ endpoints 
          schema:
            type: integer
        - name: pageCount
          in: query
          description: |
            The number of items per page, only available on /v1/ endpoints  
          schema:
            type: integer
        - name: sortBy
          in: query
          description: |
            The transaction element you want to sort the list with.
          schema:
            type: string
            default: "creationDate"
        - name: sortOrder
          in: query
          description: |
            The order you want to sort the list.
            * **DESC** for descending.
            * **ASC** for ascending.
          schema:
            type: string
            default: DESC
            enum:
              - ASC
              - DESC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeneficiaryObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
          - read_only
    post:
      tags:
        - Beneficiaries
      summary: Create Beneficiary
      description: | 
        Create a new benefeciary bank account. 

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-operation |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`beneficiary.create`](/guide/transfers/events.html#beneficiary-create) |
      operationId: postBeneficiary
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - name
                - userId
              type: object
              properties:
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                tag:
                  type: string
                  maxLength: 250
                  description: |
                    Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
            
                    Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
                userId:
                  type: integer
                  description: The unique identifier of the User to which the Beneficiary is attached.
                nickName:
                  type: string
                  description: |
                    Name chosen by end user to easily recognize the beneficiary.
                  example: "A Oak"
                name:
                  type: string
                  maxLength: 70
                  description: | 
                    Beneficiary name, linked to bank account. Allowed characters are:
                    * `a` to `z`
                    * `A` to `Z` 
                    * `0` to `9` 
                    * `/` `-` `?` `:` `(` `)` `.` `,` `'` `+` `Space`
                  example: "Alex Oak"
                address:
                  type: string
                  description: Beneficiary address, linked to bank account.
                iban:
                  type: string
                  description: |
                    Beneficiary International Bank Account Number. Mandatory if `usableForSct` is `true`.
                  example: "FR7630006000011234567890189"
                bic:
                  type: string
                  description: |
                    Beneficiary Bank Identifier Code. Mandatory if `usableForSct` is `true`.
                sepaCreditorIdentifier:
                  type: string
                  description: |
                    Beneficiary SEPA Creditor Identifier. Mandatory to validate incoming direct debit, useless other wise. Between 8 and 35 h. 
                    
                    If sddB2bWhitelist or sddCoreBlacklist is provided then sepaCreditorIdentifier is mandatory.
                sddB2bWhitelist:
                  type: array
                  description: |
                    Each unique mandate reference, with its frequency type, must
                    be explicitly allowed when doing B2B Direct Debit.
                    Furthermore, a mandate not used during more than 36 months
                    will be automatically rejected even if in the white list. If
                    provided, sepaCreditorIdentifier is mandatory.
                  items:
                    required:
                      - isRecurrent
                      - uniqueMandateReference
                    type: object
                    properties:
                      uniqueMandateReference:
                        type: string
                        description: |
                          The unique reference that unambiguiously identify a mandate signed between the user and the beneficiary. 
                          
                          See the [Unique Mandate Reference (UMR)](/guide/overview/glossary.html#unique-mandate-reference-umr) article for more information.
                      isRecurrent:
                        type: boolean
                        description: |
                          If mandate is a recurring payment, this field must be true.
                      walletId:
                        type: number
                        description: |
                          If present, the Direct Debit will be accepted only if
                          the targeted wallet is the wallet with the given
                          walletId. Without this value, the SDD can target any
                          wallets of the user. With the value specified, only
                          the explicitly authorized wallet can be targeted by
                          SDD.
                sddCoreBlacklist:
                  type: array
                  description: |
                    Core Direct Debit are accepted by default. If a Core mandate
                    is to be refused on reception, it has to be added to this
                    list. If wild char * (star) is used instead of a UMR, all
                    Direct Debit from this beneficiary will be refused. If
                    provided, sepaCreditorIdentifier is mandatory.
                  items:
                    type: string
                    description: |
                      Unique Mandate Reference that unambiguiously identify a
                      mandate signed between the user and the beneficiary. Star
                      character can also be used to reject all Direct debit from
                      the beneficiary.
                usableForSct:
                  type: boolean
                  description: |
                    Indicated if the beneficiary can be used for SEPA Credit
                    Transfer. This field is a convenient way to filter all
                    beneficiaries for a user that would like to do a Credit
                    Transfer. Indeed, beneficaries are created automatically
                    when receiving a Core Direct Debit and therefor by looking
                    at the list you won't be able to idnetify which beneficiary
                    to use on SCT.
                  default: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeneficiaryObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/beneficiaries/{beneficiaryId}:
    get:
      tags:
        - Beneficiaries
      summary: Get Beneficiary
      description: | 
        Retrieve a Beneficiary bank account based on its `id`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A|
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getBeneficiary
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: beneficiaryId
          in: path
          description: The unique identifier of the Beneficiary.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
        - name: fields
          in: query
          description: List of the object properties to be returned, allowing you to filter the response payload.
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeneficiaryObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    put:
      tags:
        - Beneficiaries
      summary: Update Beneficiary
      description: | 
        Modify a benefeciary bank account information.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-operation |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`beneficiary.update`](/guide/transfers/events.html#beneficiary-update) |
      operationId: putBeneficiary
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: beneficiaryId
          in: path
          description: The unique identifier of the Beneficiary.
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                tag:
                  type: string
                  description: |
                    Custom data that could be used by caller to search theinstance.
                nickName:
                  type: string
                  description: |
                    Name chosen by end user to easily recognize the
                    beneficiary.
                name:
                  type: string
                  maxLength: 70
                  description: | 
                    Beneficiary name, linked to bank account. Allowed characters are
                    * `a` to `z`
                    * `A` to `Z` 
                    * `0` to `9` 
                    * `/` `-` `?` `:` `(` `)` `.` `,` `'` `+` `Space`
                address:
                  type: string
                  description: Beneficiary address, linked to bank account.
                iban:
                  type: string
                  description: |
                    Beneficiary International Bank Account Number. Mandatory if
                    usableForSct is true.
                bic:
                  type: string
                  description: |
                    Beneficiary Bank Identifier Code. Mandatory if usableForSct
                    is true.
                isActive:
                  type: boolean
                  description: Whether or not the Beneficiary is active.
                sepaCreditorIdentifier:
                  type: string
                  description: |
                    Beneficiary SEPA Creditor Identifier. Mandatory to validate
                    incoming direct debit, useless other wise. Between 8 and 35
                    characters. If sddB2bWhitelist or sddCoreBlacklist is
                    provided then sepaCreditorIdentifier is mandatory.
                sddB2bWhitelist:
                  type: array
                  description: |
                    Each unique mandate reference, with its frequency type, must
                    be explicitly allowed when doing B2B Direct Debit.
                    Furthermore, a mandate not used during more than 36 months
                    will be automatically rejected even if in the white list.
                  items:
                    required:
                      - isRecurrent
                      - uniqueMandateReference
                    type: object
                    properties:
                      uniqueMandateReference:
                        type: string
                        description: |
                          The unique reference that unambiguiously identify a mandate signed between the user and the beneficiary. 
                          
                          See the [Unique Mandate Reference (UMR)](/guide/overview/glossary.html#unique-mandate-reference-umr) article for more information.
                      isRecurrent:
                        type: boolean
                        description: |
                          If mandate is a recurring payment, this field must be
                          true.
                      walletId:
                        type: number
                        description: |
                          If present, the Direct Debit will be accepted only if
                          the targeted wallet is the wallet with the given
                          walletId. Without this value, the SDD can target any
                          wallets of the user. With the value specified, only
                          the explicitly authorized wallet can be targeted by
                          SDD.
                sddCoreBlacklist:
                  type: array
                  description: |
                    Core Direct Debit are accepted by default. If a Core mandate
                    is to be refused on reception, it has to be added to this
                    list. If wild char * (star) is used instead of a UMR, all
                    Direct Debit from this beneficiary will be refused.
                  items:
                    type: string
                    description: |
                      Unique Mandate Reference that unambiguiously identify a
                      mandate signed between the user and the beneficiary. Star
                      character can also be used to reject all Direct debit from
                      the beneficiary.
                usableForSct:
                  type: boolean
                  description: |
                    Indicated if the beneficiary can be used for SEPA Credit
                    Transfer. This field is a convenient way to filter all
                    beneficiaries for a user that would like to do a Credit
                    Transfer. Indeed, beneficaries are created automatically
                    when receiving a Core Direct Debit and therefor by looking
                    at the list you won't be able to idnetify which beneficiary
                    to use on SCT.
                  default: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeneficiaryObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/beneficiaries/validation:
    post:
      summary: Request Beneficiary Validation
      description: |
        Request the validation of a beneficiary bank account. 
        The resulting `beneficiaryValidationId` is required as a prerequisite for the following payouts:
        * [SEPA Credit Transfer](/guide/transfers/credit-transfer.html#emitted-credit-transfers-scte)
        * [SEPA Instant Credit Transfer](/guide/transfers/credit-transfer-inst.html#emitted-instant-credit-transfers-scte-inst)

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A|
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      tags:
        - Beneficiaries
      operationId: postBeneficiaryVerification
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - beneficiaryName
                - beneficiaryIBAN
              properties:
                beneficiaryName:
                  type: string
                  minLength: 2
                  maxLength: 100
                  description: The name of the account owner, as declared in the Beneficiary object, for comparison with the name registered at their bank.
                  example: "Alex Oak"
                beneficiaryIBAN:
                  type: string
                  description: The IBAN of the account to check.
                  example: "DE15801640509362882000"
                recurrenceType:
                  type: string
                  default: "default"
                  description: |
                    Must be set to `scheduled` if you've put in place your own system to schedule payments at a later date (one-time or recurring). 
                    Scheduled recurrence allow you to use of the same `beneficiaryValidationId` for the subsequent payments.
                  enum: 
                    - 'default'
                    - 'scheduled'
      responses:
        '200':
          description: Verification request accepted and processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeneficiaryValidationObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write

  /v1/beneficiaries/validation/{beneficiaryValidationId}:
    get:
      tags: 
        - Beneficiaries
      summary: Get Beneficiary Validation
      description: |
        Retrieve a beneficiary validation result using its Id.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A|
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getBeneficiaryValidation
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - in: path
          name: beneficiaryValidationId
          required: true
          description: The unique identifier of the beneficiary validation.
          schema:
            type: string
            format: uuid
            example: "f8e4a7b2-c1d3-4e5a-8b0f-9c2d1e0a3b5c"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  beneficiaryValidationId:
                    type: string
                    format: uuid
                    description: The unique identifier of the validation object.
                    example: "f8e4a7b2-c1d3-4e5a-8b0f-9c2d1e0a3b5c"
                  createdDate:
                    type: string
                    format: date-time
                    description: The date and time at which the beneficiary validation was created.
                    example: "2025-08-29T16:52:27.379Z"
                  consumed:
                    type: boolean
                    description: |
                      Whether the beneficiary validation was used for a payout.
                    
                      Each validation can be used only once; you must create a new beneficiary validation request for each payout.
                  vop:
                    type: object
                    properties:
                      result:
                        type: string
                        description: |
                          Whether the account owner matches the information declared in your systems.

                          See [Validation result](/guide/transfers/beneficiaries.html#validation-result-result) to learn more about each result and the message to display to the end user.
                        enum: ["MTCH", "NMTC", "CMTC", "NOAP"]
                        example: "CMTC"
                      matchedName:
                        type: string
                        description: |
                          The name declared for the account owner in the banking system. Only populated in case of `CMTC` result.
                        nullable: true
                        example: "Axel Oak"
                      reasonCode:
                        type: string
                        description: | 
                          The reason for which the request to the bank didn't result in a conclusive verification. 
                          Only populated in case of `NOAP` result.

                          See [Reason codes](/guide/transfers/beneficiaries.html#reason-codes-reasoncode) for the description of each result.
                        nullable: true
                        enum: [ "9001", "9007", "9008", "9009", "9010" ]
                      recurrenceType:
                        type: string
                        description: |
                          Must be set to `scheduled` if you've put in place your own system to schedule payments at a later date (one-time or recurring).
                          Scheduled recurrence allow you to use of the same `beneficiaryValidationId` for the subsequent payments.
                        enum:
                          - default
                          - scheduled
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only

  /v1/internationalBeneficiaries/requirements:
    get:
      tags:
        - Beneficiaries
      summary: Get International Beneficiary Requirements
      description: |
        Retrieve the list of required fields to create an international transfer beneficiary.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getBenefRequirements
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: sourceCurrency
          in: query
          required: true
          description: |
            The initial currency of the emitted transfer. For now the only sourceCurrency allowed is EUR.
          schema:
            type: string
            format: ISO 4217
            example: "EUR"
        - name: targetCurrency
          in: query
          required: true
          description: |
            The currency for the beneficiary wallet.
          schema:
            type: string
            format: ISO 4217
            default: "USD"
        - name: amount
          in: query
          required: true
          description: |
            The amount to be emitted.
          schema:
            type: string
            format: float
            example: "24.68"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                    - type
                    - title
                    - fields
                  properties:
                    type:
                      type: string
                    title:
                      type: string
                    fields:
                      type: array
                      items:
                        type: object
                        required:
                          - name
                          - group
                        properties:
                          name:
                            type: string
                          group:
                            type: array
                            items:
                              type: object
                              required:
                                - key
                                - name
                                - type
                                - refreshRequirementsOnChange
                              properties:
                                key:
                                  type: string
                                name:
                                  type: string
                                type:
                                  type: string
                                refreshRequirementsOnChange:
                                  type: boolean
                                displayFormat:
                                  type: string
                                example:
                                  type: string
                                minLength:
                                  type: number
                                maxLength:
                                  type: number
                                validationRegexp:
                                  type: string
                                valuesAllowed:
                                  type: array
                                  items:
                                    type: object
                                    required:
                                      - key
                                      - name
                                    properties:
                                      key:
                                        type: string
                                      name:
                                        type: string
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write

  /v1/internationalBeneficiaries:
    post:
      tags:
        - Beneficiaries
      summary: Create International Beneficiary
      description: |
        Create an International Beneficiary to emit international transfers.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-operation |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`internationalBeneficiary.create`](/guide/transfers/events.html#internationalbeneficiary-create) |
      operationId: postIntBenef
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - name
                - userId
                - type
                - currency
                - address
                - details
              type: object
              properties:
                userId:
                  type: integer
                  description: The unique identifier of the User to which the International Beneficiary is attached.
                nickName:
                  type: string
                  description: |
                    Name chosen by end user to easily recognize the beneficiary.
                  example: "A Oak"
                name:
                  type: string
                  description: | 
                    International Beneficiary name, linked to bank account.
                  example: "Alex Oak"
                type:
                  type: string
                  description: | 
                    Specifies the system used for the transaction.
                  example: "ACH"
                currency: 
                  type: string
                  description: Specifies the target attached to the international beneficiary (target currency)
                  format: ISO 4217
                  example: "USD"
                address:
                  type: object
                  description: |
                    The address of the international beneficiary. Required sub-fields: `streetName`, `buildingNumber`, `city`, `postalCode`, `country`. The `state` field is only required for United States, Brazil, Australia, and Canada.
                  required:
                    - streetName
                    - buildingNumber
                    - city
                    - postalCode
                    - country
                  properties:
                    streetName:
                      type: string
                      example: "Liberty Island"
                    buildingNumber:
                      type: string
                      example: "1"
                    city:
                      type: string
                      example: "New York"
                    state:
                      type: string
                      example: "New York"
                      description: |
                        Required if country is United States, Brazil, Australia, or Canada.
                    postalCode:
                      type: string
                      example: "10004"
                    country:
                      type: string
                      example: "United States"
                details:
                  type: object
                  description: |
                    Mandatory information regarding the beneficiary bank account. The content depends on the requirements.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternationalBeneficiaryObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
      security:
        - OAuth2:
          - read_write
  /v1/internationalBeneficiaries/{internationalBeneficiaryId}:
    get:
      tags:
        - Beneficiaries
      summary: Get International Beneficiary
      description: | 
        Retrieve an International Beneficiary based on its id.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A|
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getInterBeneficiary
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: internationalBeneficiaryId
          in: path
          required: true
          description: |
            The unique identifier of the International Beneficiary.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternationalBeneficiaryObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
    delete:
      tags:
        - Beneficiaries
      summary: Delete International Beneficiary
      description: | 
        Delete an International Beneficiary. This action is irreversible.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`internationalBeneficiary.cancel`](/guide/transfers/events.html#internationalbeneficiary-cancel) |
      operationId: deleteInterBeneficiary
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: internationalBeneficiaryId
          in: path
          required: true
          description: |
            The unique identifier of the International Beneficiary.
          schema:
            type: string
      responses:
        '204':
          description: Beneficiary successfully deleted
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
          - read_only
  /v1/quote:
    post:
      tags:
        - Payouts
      summary: Create International Transfer Quote
      description: | 
        Create a quotation for an international transfer.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: postQuote
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - internationalBeneficiaryId
              type: object
              properties:
                internationalBeneficiaryId:
                  type: string
                  description: The unique identifier of International Beneficiary.
                sourceAmount:
                  type: number
                  example: 123.45
                  description: |
                    The amount stated in the source currency.
                sourceCurrency:
                  type: string
                  format: ISO 4217
                  description: |
                    The source currency. As of today, can only be `EUR`.
                  default: "EUR"
                targetAmount:
                  type: number
                  example: 121.98
                targetCurrency:
                  type: string
                  format: ISO 4217
                  description: |
                    The currency of the target account. Must be among the [emission supported currencies](/guide/transfers/international.html#supported-currencies).
                  example: "USD"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
          - read_only
  /v1/quote/{quoteId}:
    get:
      tags:
        - Payouts
      summary: Get International Transfer Quote
      description: | 
        Retrieve an International Transfer Quote

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getQuote
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: quoteId
          in: path
          required: true
          description: |
            The unique identifier of the International Beneficiary.
          schema:
            type: string
            maxLength: 250
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
          - read_only 

  /v1/businesssearchs:
    get:
      tags:
        - Businesses
      summary: Search Businesses
      operationId: searchBusiness
      description: |
        Check information regarding a legal entity.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: country
          in: query
          description: |
            In which country to search. Format: [ISO 3166-1 alpha-2](/guide/api-basics/data-format.html#countries)
          required: true
          example: "FR"
          schema:
            type: string
            format: ISO 3166-1 alpha-2
        - name: nameExact
          in: query
          description: |
            Business exact name. Exclusive with `nameMatchBeginning` and `nameClosestKeywords`.
          schema:
            type: string
        - name: nameMatchBeginning
          in: query
          description: |
            Business names begin with. Exclusive with `nameExact` and `nameClosestKeywords`.
          schema:
            type: string
        - name: nameClosestKeywords
          in: query
          description: |
            Business names closed to keywords. Exclusive with `nameExact` and `nameMatchBeginning`.
          schema:
            type: string
        - name: registrationNumber
          in: query
          description: | 
            Business registration number. Required if the `vatNumber` isn't provided.
          schema:
            type: string
        - name: vatNumber
          in: query
          description: | 
            Business VAT number. Required if the `registrationNumber` isn't provided.
          schema:
            type: string
        - name: phoneNumber
          in: query
          description: Business phone number.
          schema:
            type: string
        - name: addressStreet
          in: query
          description: Business' street address.
          schema:
            type: string
        - name: addressCity
          in: query
          description: Business' city address.
          schema:
            type: string
        - name: addressPostalCode
          in: query
          description: Business' postal code address.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    businessinformations:
                      type: array
                      items:
                        type: object
                        properties:
                          legalName:
                            type: string
                            description: Business commercial name.
                            example: "Tree Company"
                          phone:
                            type: string
                            description: Business phone number.
                          legalTvaNumber:
                            type: string
                            description: Business VAT number.
                            example: "FR018798XXXXX"
                          legalRegistrationNumber:
                            type: string
                            description: Business registration number.
                            example: "879804805XXXXX"
                          status:
                            type: string
                            description: |
                              | Code | Description |
                              | ---- | ----------- |
                              |  D   | Deleted     |
                              |  N   | Company non diffusible (Insee) |
                              |  I   | Inactive (Insee) |
                              |  A   | Economically active |
                              |  C   | Closed |
                              |  T   | Transferred |
                              |  S   | Economically stopped (Insee) |
                              |  L   | Liquidation |
                              |  O   | Dormant company |
                            enum:
                              - A
                              - C
                              - D
                              - I
                              - L
                              - N
                              - O
                              - S
                              - T
                          officeType:
                            type: integer
                            description: |
                              Can be one of the following:
                              * `0` – Secondary establishment
                              * `1` – Headquarter
                            enum: [0,1]
                          safeNumber:
                            type: string
                            description: Business SAFE number.
                          activityType:
                            type: string
                            description: Business sector. Code NAF in France.
                          externalId:
                            type: string
                            description: Business external id.
                          address1:
                            type: string
                            description: The address of the business.
                          postcode:
                            type: string
                            description: The postal code of the business' address.
                          city:
                            type: string
                            description: The city of the business' address.
                            example: "PARIS"
                          state:
                            type: string
                            description: Business' province.
                          country:
                            type: string
                            description: | 
                              The country of the business' address.
                            format: ISO 3166-1 alpha-2
                            example: "FR"
                          tradename:
                            type: string
                            description: The trade name of the legal entity.
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
  /v1/businessinformations:
    get:
      tags:
        - Businesses
      summary: Get Business Information
      operationId: getBusinessInfo
      description: |
        The get business information endpoint returns all already known business information. End user will have then to verify/correct it.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: country
          in: query
          description: |
            In which country to search. Format [ISO 3166-1 alpha-2](/guide/api-basics/data-format.html#countries)
          required: true
          example: "FR"
          schema:
            type: string
            format: ISO 3166-1 alpha-2
        - name: externalId
          in: query
          description: Unique business external id, as given in businesssearch response.
          schema:
            type: string
        - name: registrationNumber
          in: query
          description: Unique business registration number.
          schema:
            type: string
        - name: vatNumber
          in: query
          description: Unique business VAT number.
          schema:
            type: string
      responses:
        '200':
          description: A business information response
          content:
            'application/json':
              schema:
                type: object
                properties:
                  businessinformations:
                    type: array
                    items:
                      type: object
                      properties:
                        legalName:
                          type: string
                          description: Business commercial name.
                          example: "Tree Company"
                        legalRegistrationNumber:
                          type: string
                          description: Business registration number.
                          example: "879804805XXXXX"
                        legalRegistrationDate:
                          type: string
                          description: Business registration date.
                        legalForm:
                          type: string
                          description: |
                            The legal form/category of the company. See the [Legal Forms](/guide/users/introduction.html#legal-forms-legalform) section for more information.
                        legalShareCapital:
                          type: number
                          description: Business share capital.
                        legalSector:
                          type: string
                          description: |
                            The Business Sector of the company (NAF or NACE code in France). The expected format depends on `legalSectorType`

                            You may check out [the authoritative list](https://www.insee.fr/fr/information/2120875)
                        legalAnnualTurnOver:
                          type: string
                          description: |
                            Business annual turnover range in k€.
                          enum:
                            - ''
                            - 0-39
                            - 40-99
                            - 100-249
                            - 250-999
                            - 1000-2999
                            - 3000-9999
                            - 10000-99999
                            - 100000-*
                        legalNetIncomeRange:
                          type: string
                          description: |
                            Business annual net income in k€. Negative values are only accepted for legal entities.
                          enum:
                            - ''
                            - '*--500'
                            - '-499--150'
                            - '-149--50'
                            - '-49--10'
                            - '-9--1'
                            - 0-4
                            - 5-9
                            - 10-49
                            - 50-149
                            - 150-499
                            - 500-*
                        legalNumberOfEmployeeRange:
                          type: string
                          description: |
                            Business workforce.
                          enum:
                            - ''
                            - '0'
                            - 1-9
                            - 10-99
                            - 100-249
                            - 250-*
                        phone:
                          type: string
                          description: Business phone number.
                        email:
                          type: string
                          description: Business generic email.
                        address1:
                          type: string
                          description: Business' street
                        postcode:
                          type: string
                          description: Business' postal code
                        city:
                          type: string
                          description: Business' city
                        state:
                          type: string
                          description: Business' province
                        country:
                          type: string
                          description: Business' country
                          format: ISO 3166-1 alpha-2
                          example: "FR"
                        status:
                          type: string
                          description: |
                            | Code | Description |
                            | ---- | ----------- |
                            |  D   | Deleted     |
                            |  N   | Company non diffusible (Insee) |
                            |  I   | Inactive (Insee) |
                            |  A   | Economically active |
                            |  C   | Closed |
                            |  T   | Transferred |
                            |  S   | Economically stopped (Insee) |
                            |  L   | Liquidation |
                            |  O   | Dormant company |
                          enum: [A,C,D,I,L,N,O,S,T]
                        tradename:
                          type: string
                          description: Business trade name
                        users:
                          type: array
                          items:
                            type: object
                            properties:
                              firstname:
                                type: string
                                description: Representative's first name.
                              lastname:
                                type: string
                                description: Representative's last name.
                              fullnames:
                                type: string
                                description: Representative's full names.
                              birthday:
                                type: string
                                description: Representative's birthdate. Format YYYY-MM-DD
                              parentType:
                                type: string
                                description: Representative's position in company
                                enum:
                                  - Accounts controller
                                  - Active partner
                                  - Administrative director
                                  - Administrator
                                  - Auditor
                                  - Authorized agent
                                  - Censor
                                  - Chairman of the Board
                                  - Chief Executive Officer
                                  - Chief Technical Officer
                                  - Chief accountant
                                  - Co-managing partner
                                  - Conciliator
                                  - Concordat commissioner
                                  - Delegated administrator
                                  - Delegated managing director
                                  - Deputy auditor
                                  - Deputy governor
                                  - Deputy managing director
                                  - Developer
                                  - Financial director
                                  - General secretary
                                  - Governor
                                  - Guardian
                                  - Honorary president
                                  - Judge-commissioner
                                  - Judicial representative
                                  - Liquidator
                                  - Management advisor
                                  - Management agent
                                  - Management controller
                                  - Manager
                                  - Managing director
                                  - Managing director not administrator
                                  - Member
                                  - Member of the control committee
                                  - Member of the control council
                                  - Member of the management board
                                  - Member of the management council
                                  - Member of the supervisory council
                                  - Not associated manager
                                  - Other manager
                                  - Partner
                                  - Person having the power to usually involve the company
                                  - Person in charge abroad
                                  - Personal business manager
                                  - Plan commissioner
                                  - President
                                  - President of the control council
                                  - President of the management board
                                  - President of the supervisory council
                                  - Receiver
                                  - Receiver/representative of the creditors
                                  - Representative in France
                                  - Representative in France of a foreign company
                                  - Representative of the creditors
                                  - Sales director
                                  - Secretary
                                  - Spouse-associate
                                  - Statutory auditor
                                  - Substitute judge-commissioner
                                  - Supervision commissioner
                                  - Temporary administrator
                                  - Treasurer
                                  - Unique managing director
                                  - Vice-president
                                  - Vice-president of the management board
                                  - Vice-president of the supervisory council
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
  /v1/cards:
    get:
      tags:
        - Cards
      summary: Search Cards
      description: | 
        Retrieve Cards based on search criteria.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getCards
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: cardId
          in: query
          description: The unique identifier of the Card.
          schema:
            type: integer
            example: 12345
        - name: userId
          in: query
          description: The unique identifier of the cardholder.
          schema:
            type: integer
            example: 12345
        - name: walletId
          in: query
          description: The unique identifier of the wallet.
          schema:
            type: integer
            example: 12345
        - name: embossedName
          in: query
          description: |
            The name embossed on the card. This is a non-strict search which returns all the cards with embossed values close to the one entered.
          schema:
            type: string
            example: ALEX OAK
        - name: publicToken
          in: query
          description: Public token of the card
          schema:
            type: string
            example: "104695621"
        - name: permsGroup
          in: query
          description: |
            Permissions group of the card. 

            See [available values on the documentation](/guide/cards/restrictions-limits.html#permission-groups-permsgroup)
          schema:
            type: string
            enum: 
              - "TRZ-CU-001"
              - "TRZ-CU-002"
              - "TRZ-CU-003"
              - "TRZ-CU-004"
              - "TRZ-CU-005"
              - "TRZ-CU-006"
              - "TRZ-CU-007"
              - "TRZ-CU-008"
              - "TRZ-CU-009"
              - "TRZ-CU-010"
              - "TRZ-CU-011"
              - "TRZ-CU-012"
              - "TRZ-CU-013"
              - "TRZ-CU-014"
              - "TRZ-CU-015"
              - "TRZ-CU-016"
        - name: isPhysical
          in: query
          description: |
            Whether or not the card is a Physical Card. Values can be:
              * `1` – Physical card
              * `0` – Virtual card
          schema:
            type: integer
            enum: [0,1]
        - name: isConverted
          in: query
          description: |
            Whether or not the card is a Virtual Card that has been converted into a Physical Card. Values can be:
              * `1` – Physical card converted from a virtual card
              * `0` – Not converted, virtual card only
          schema:
            type: integer
            enum: [0,1]
        - name: lockStatus
          in: query
          description: | 
            The Status of the card, indicating whether it is locked, lost, or destroyed for instance.

            While this field is an integer, it returns a plaintext value. See the full list of `lockStatus`in the [Block a Card](/guide/cards/modification.html#status) article.
          schema:
            type: integer
            enum: [0,1,2,3,4,5,6,7]
        - name: mccRestrictionGroupId
          in: query
          description: |
            The merchant category restriction group (`mccRestrictionGroup`) applied to the card.
          schema:
            type: integer
            example: 12345
        - name: merchantRestrictionGroupId
          in: query
          description: |
            The merchant Id restriction group (`merchantRestrictionGroupId`) applied to the card.
          schema:
            type: integer
            example: 12345
        - name: countryRestrictionGroupId
          in: query
          description: |
            The country restriction group (`countryRestrictionGroupId`) applied to the card.
          schema:
            type: integer
            example: 12345
        - name: pageNumber
          in: query
          description: |
            The page number, only available on /v1/ endpoints 
          schema:
            type: integer
            example: 2
        - name: pageCount
          in: query
          description: |
            The number of items per page, only available on /v1/ endpoints  
          schema:
            type: integer
            example: 50
        - name: sortBy
          in: query
          description: |
            The reference value for sorting the list.
          schema:
            type: string
            default: "id"
            enum:
              - "id"
              - "createdDate"
        - name: sortOrder
          in: query
          description: |
            The order you want to sort the list.
            * **DESC** for descending.
            * **ASC** for ascending.
          schema:
            type: string
            default: DESC
            enum:
              - ASC
              - DESC
        - name: createdDateFrom
          in: query
          description: |
            The creation date from which you want to filter the request result.

            Format: `YYYY-MM-DD HH:mm:ss`. 
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2025-01-01 12:00:00"
        - name: createdDateTo
          in: query
          description: |
            The creation date up to which you want to filter the request result.
            
            Format: `YYYY-MM-DD HH:mm:ss`. 
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2025-12-01 12:00:00"
        - name: updatedDateFrom
          in: query
          description: |
            The modification date from which you want to filter the request result. 

            Format: `YYYY-MM-DD HH:mm:ss`. 
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2025-01-01 12:00:00"
        - name: updatedDateTo
          in: query
          description: |
            The modification date up to which you want to filter the request result.

            Format: `YYYY-MM-DD HH:mm:ss`. 
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2025-12-01 12:00:00"
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/CardObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
  /v1/cards/{cardId}:
    get:
      tags:
        - Cards
      summary: Get Card
      description: | 
        Retrieve a Card based on its `id`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getCard
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: path
          description: The unique identifier of the Card.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/CardObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    put:
      tags:
        - Cards
      summary: Update Card
      operationId: putCard
      description: |
        Update the restriction groups of the card, as well as the `cardTag`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`card.update`](/guide/cards/events.html#card-update) |
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: path
          description: The unique identifier of the Card.
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                mccRestrictionGroupId:
                  type: integer
                  description: |
                    The merchant category restriction group (`mccRestrictionGroup`) to apply to the card.
                merchantRestrictionGroupId:
                  type: integer
                  description: |
                    The merchant Id restriction group (`merchantRestrictionGroupId`) to apply to the card.
                countryRestrictionGroupId:
                  type: integer
                  description: |
                    The country restriction group (`countryRestrictionGroupId`) to apply to the card.
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                cardTag:
                  type: string
                  description: |
                    Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
                    
                    Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/CardObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/cards/CreateVirtual:
    post:
      tags:
        - Cards
      summary: Create Virtual Card
      operationId: postCardVirtual
      description: |
        Create a new virtual card. To use a card, it must be activated (`/v1/cards/{cardId}/Activate`).

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`card.createvirtual`](/guide/cards/events.html#card-createvirtual) |
      #parameters: 
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - userId
                - walletId
                - permsGroup
                - cardPrint
              type: object
              properties:
                userId:
                  type: integer
                  description: The unique identifier of the cardholder.
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                walletId:
                  type: integer
                  description: The unique identifier of the Wallet the card is attached to.
                permsGroup:
                  type: string
                  description: | 
                    Permissions defining which features are enabled for the Card. See the [Permissions Groups](/guide/cards/restrictions-limits.html#permission-groups-permsgroup) article for more information.
                  enum:
                    - TRZ-CU-001
                    - TRZ-CU-002
                    - TRZ-CU-003
                    - TRZ-CU-004
                    - TRZ-CU-005
                    - TRZ-CU-006
                    - TRZ-CU-007
                    - TRZ-CU-008
                    - TRZ-CU-009
                    - TRZ-CU-010
                    - TRZ-CU-011
                    - TRZ-CU-012
                    - TRZ-CU-013
                    - TRZ-CU-014
                    - TRZ-CU-015
                    - TRZ-CU-016	
                cardTag:
                  type: string
                  maxLength: 250
                  description: |
                    Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
                    
                    Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
                batchDeliveryId:
                  type: integer
                  description: |
                    Batch delivery identifier, which value must be between `1` and `238327`.

                    This feature is not enabled by default, see [Customization](/guide/cards/creation.html#batch-delivery-batchdeliveryid) for more information.
                limitAtmYear:
                  type: integer
                  description: ATM operations limit for a sliding year. No default value.
                limitAtmMonth:
                  type: integer
                  description: ATM operations limit for a sliding month. No default value.
                limitAtmWeek:
                  type: integer
                  description: ATM operations limit for a sliding week. Default value €2000.
                  default: 2000
                limitAtmDay:
                  type: integer
                  description: ATM operations limit for a single day. Default value €1000.
                  default: 1000
                limitAtmAll:
                  type: integer
                  description: ATM operations limit from beginning. No default value.
                limitPaymentYear:
                  type: integer
                  description: POS operations limit for a sliding year. No default value.
                limitPaymentMonth:
                  type: integer
                  description: POS operations limit for a sliding month. No default value.
                limitPaymentWeek:
                  type: integer
                  description: POS operations limit for a sliding week. Default value €3000.
                  default: 3000
                limitPaymentDay:
                  type: integer
                  description: POS operations limit for a single day. Default value €2000.
                  default: 2000
                limitPaymentAll:
                  type: integer
                  description: POS operations limit from beginning. No default value.
                paymentDailyLimit:
                  type: number
                  format: float
                  description: | 
                    POS operations limit for a single day including cents. The decimal delimiter must be ".". No default value.

                    For food vouchers use cases only.
                pin: 
                  type: string
                  description: The PIN code value of the card.
                cardPrint:
                  type: string
                  description: |
                    The [Card Program](/guide/cards/introduction.html#card-program) to associate to the Card and the options provided with it. This information is shared with you by Treezor.
                anonymous:
                  type: integer
                  description: |
                    Whether the cards are to belong to [Anonymous Users](/guide/users/physical.html#anonymous-users). If so set the value to `1`, otherwise `0`.
                    When set to `1`, there is no embossed name on the card.
                  enum: [0,1]
                sendToParent:
                  type: integer
                  description: | 
                    Whether the card should be sent to the cardholder's Parent User or Source User. 
                    When set to `1`, the delivery address fields will be automatically filled in with the parent or source user's address.
                  enum: [0,1]
                sourceUserId:
                  type: integer
                  description: |
                    The unique identifier of the source User to use for the card delivery address when `sendToParent` is set to `1`. 

                    If not provided, the cardholder's `parentUserId` is used instead (legacy behavior).
                mccRestrictionGroupId:
                  type: integer
                  description: |
                    The merchant category restriction group (`mccRestrictionGroup`) to apply to the card.
                merchantRestrictionGroupId:
                  type: integer
                  description: |
                    The merchant Id restriction group (`merchantRestrictionGroupId`) to apply to the card.
                countryRestrictionGroupId:
                  type: integer
                  description: |
                    The country restriction group (`countryRestrictionGroupId`) to apply to the card.
                embossLegalName:
                  type: boolean
                  description: |
                    When set to `true`, embosses the corresponding user's `legalName` on the card. See the [embossed name](/guide/cards/creation.html#embossed-name-embossedname) article for more information.

                    Depending on the configuration, the legal name may be displayed regardless of the value of this field.
                  default: false
                logoId:
                  type: string
                  maxLength: 30
                  description: |
                    The file name of the logo for the card, as uploaded to the manufacturer. Learn more in the [Logo](/guide/cards/creation.html#logo-logoid) article.
                  example: "MyLogoFile.png"
                logoBackId:
                  type: string
                  description: |
                    The file name of the logo for the back of the card, as uploaded to the manufacturer. Learn more in the [Back Logo](/guide/cards/creation.html#back-logo-logobackid) article.
                  maxLength: 30
                  example: "MyBackLogoFile.png"
                designCode:
                  type: string
                  maxLength: 2
                  description: |
                    Customization code for the card design. If missing, falls back to the default Design Code. Learn more in the [Designs](/guide/cards/creation.html#designs-designcode) article.
                  format: alphanumeric
                packageId:
                  type: string
                  maxLength: 8
                  description: Packaging reference for card shipping. Max. 8 characters.
                  example: "Pkg123"
                deliveryMethod:
                  type: integer
                  description: | 
                    The method the manufacturer uses to send the cards (e.g., delivery with or without tracking). 
                    Learn more in the [Card Delivery Method](/guide/cards/creation.html#card-delivery-method-deliverymethod) article.
                pinMailer:
                  type: integer
                  description: |
                    You can request the card manufacturer to send the card PIN code by letter.
                    Learn more in the [Pin Mailer](/guide/cards/creation.html#pin-mailer-pinmailer) article.
                  enum: [0,1]
                customizedInfo:
                  type: string
                  maxLength: 27
                  description: |
                    Customized text to be displayed on the card.

                    If populated, it must: 
                    * Be alphanumeric
                    * Contain at most 27 characters
                    * Not contain `!"#%'(),:;<>?@[]^` or the backtick symbol.
                freeCustomizedInfo:
                  type: string
                  maxLength: 50
                  description: |
                    More customized text to be displayed on the card.

                    If populated, it must: 
                    * Be alphanumeric
                    * Contain at most 50 characters
                    * Not contain `!"#%'(),:;<>?@[]^` or the backtick symbol.
                letterCustomizedInfo:
                  type: string
                  maxLength: 50
                  description: |
                    Customized text for the letter that is joined to the card.

                    If populated, it must:
                    * Be alphanumeric
                    * Contain at most 50 characters
                    * Not contain `!"#%'(),:;<>?@[]^` or the backtick symbol.
                cardLanguages:
                  type: string
                  format: ISO 639-1 alpha-2
                  maxLength: 8
                  description: |
                    The language preferences for the card for [ATMs](/guide/overview/glossary.html#automated-teller-machine-atm), in the order of preference. For instance, for French and English, you have to enter "fren".

                    While this information is well taken into account in the card configuration, please note that the API will not return the value.
                    
                    Must be alphabetic and max. 8 characters. Format: [ISO 639-1 alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).
                  example: "fren"
                  nullable: true
                isTemporary:
                  type: boolean
                  default: false
                  description: |
                    Whether the card is temporary. If set to `true`, then you can create a virtual card with a predefined lifespan and spending limit.
                    In such cases, the `expiryDate` must be defined. See [Creating Temporary Cards](/guide/cards/creation.html#creating-temporary-cards) for more information.
                startDate:
                  type: string
                  format: date
                  description: |
                    The date of activation of a temporary card. This field can only be filled when `isTemporary` is set to `true`.
                  example: "2025-01-01"
                expiryDate:
                  type: string
                  format: date
                  description: |
                    The date until which the card is valid. This field is required when `isTemporary` is set to `true`.
                  example: "2025-01-31"
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/CardObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/cards/RequestPhysical:
    post:
      tags:
        - Cards
      summary: Create Physical Card
      operationId: postCardPhysical
      description: |
        Create a new physical card. To use a card, it must be activated (`/cards/{id}/Activate`).

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`card.requestphysical`](/guide/cards/events.html#card-requestphysical) |
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - userId
                - walletId
                - permsGroup
                - cardPrint
              type: object
              properties:
                userId:
                  type: integer
                  description: The unique identifier of the cardholder.
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                walletId:
                  type: integer
                  description: The unique identifier of the Wallet the card is attached to.
                permsGroup:
                  type: string
                  description: | 
                    Permissions defining which features are enabled for the Card. See the [Permissions Groups](/guide/cards/restrictions-limits.html#permission-groups-permsgroup) article for more information.
                  enum:
                    - TRZ-CU-001
                    - TRZ-CU-002
                    - TRZ-CU-003
                    - TRZ-CU-004
                    - TRZ-CU-005
                    - TRZ-CU-006
                    - TRZ-CU-007
                    - TRZ-CU-008
                    - TRZ-CU-009
                    - TRZ-CU-010
                    - TRZ-CU-011
                    - TRZ-CU-012
                    - TRZ-CU-013
                    - TRZ-CU-014
                    - TRZ-CU-015
                    - TRZ-CU-016	
                cardTag:
                  type: string
                  description: |
                    This attribute is a string which can store a maximum of 250 characters that you are free to populate to suit your needs
                    
                    You can [read more about tags](/guide/api-basics/objects-tags.html)
                batchDeliveryId:
                  type: integer
                  description: |
                    Batch delivery identifier, which value must be between `1` and `238327`.

                    This feature is not enabled by default, see [Customization](/guide/cards/creation.html#batch-delivery-batchdeliveryid) for more information.
                limitAtmYear:
                  type: integer
                  description: ATM operations limit for a sliding year. No default value.
                limitAtmMonth:
                  type: integer
                  description: ATM operations limit for a sliding month. No default value.
                limitAtmWeek:
                  type: integer
                  default: 2000
                  description: ATM operations limit for a sliding week. Default value €2000.
                limitAtmDay:
                  type: integer
                  default: 1000
                  description: ATM operations limit for a single day. Default value €1000.
                limitAtmAll:
                  type: integer
                  description: ATM operations limit from beginning. No default value.
                limitPaymentYear:
                  type: integer
                  description: POS operations limit for a sliding year. No default value.
                limitPaymentMonth:
                  type: integer
                  description: POS operations limit for a sliding month. No default value.
                limitPaymentWeek:
                  type: integer
                  default: 3000
                  description: POS operations limit for a sliding week. Default value €3000.
                limitPaymentDay:
                  type: integer
                  default: 2000
                  description: POS operations limit for a single day. Default value €2000.
                limitPaymentAll:
                  type: integer
                  description: POS operations limit from beginning. No default value.
                paymentDailyLimit:
                  type: number
                  format: float
                  description: | 
                    POS operations limit for a single day including cents. The decimal delimiter must be ".". No default value.

                    For food vouchers use cases only.
                  example: 25.00
                pin: 
                  type: string
                  description: The PIN code value of the card.
                cardPrint:
                  type: string
                  description: |
                    The [Card Program](introduction.html#card-program) to associate to the Card and the options provided with it. This information is shared with you by Treezor.
                anonymous:
                  type: integer
                  description: |
                    Whether the cards are to belong to [Anonymous Users](/guide/users/physical.html#anonymous-users). If so set the value to `1`, otherwise `0`.
                    When set to `1`, there is no embossed name on the card.
                  enum: [0,1]
                sendToParent:
                  type: integer
                  description: | 
                    Whether the card should be sent to the cardholder's Parent User or Source User. 

                    When set to `1`, the delivery address fields will be automatically filled in with the parent or source user's address.
                  enum: [0,1]
                sourceUserId:
                  type: integer
                  description: |
                    The unique identifier of the source User to use for the card delivery address when `sendToParent` is set to `1`. 

                    If not provided, the cardholder's `parentUserId` is used instead (legacy behavior).
                mccRestrictionGroupId:
                  type: integer
                  description: |
                    The merchant category restriction group (`mccRestrictionGroup`) to apply to the card.
                merchantRestrictionGroupId:
                  type: integer
                  description: |
                    The merchant Id restriction group (`merchantRestrictionGroupId`) to apply to the card.
                countryRestrictionGroupId:
                  type: integer
                  description: |
                    The country restriction group (`countryRestrictionGroupId`) to apply to the card.
                embossLegalName:
                  type: boolean
                  description: |
                    When set to `true`, embosses the corresponding user's `legalName` on the card. See the [embossed name](/guide/cards/creation.html#embossed-name-embossedname) article for more information.

                    Depending on the configuration, the legal name may be displayed regardless of the value of this field.
                  default: false
                logoId:
                  type: string
                  maxLength: 30
                  description: |
                    The file name of the logo for the card, as uploaded to the manufacturer. Learn more in the [Logo](/guide/cards/creation.html#logo-logoid) article.
                  example: "MyLogoFile.png"
                logoBackId:
                  type: string
                  description: |
                    The file name of the logo for the back of the card, as uploaded to the manufacturer. Learn more in the [Back Logo](/guide/cards/creation.html#back-logo-logobackid) article.
                  maxLength: 30
                  example: "MyBackLogoFile.png"
                designCode:
                  type: string
                  maxLength: 2
                  description: |
                    Customization code for the card design. If missing, falls back to the default Design Code. Learn more in the [Designs](/guide/cards/creation.html#designs-designcode) article.
                  format: alphanumeric
                packageId:
                  type: string
                  maxLength: 8
                  description: Packaging reference for card shipping. Max. 8 characters.
                  example: "Pkg123"
                deliveryMethod:
                  type: integer
                  description: | 
                    The method the manufacturer uses to send the cards (e.g., delivery with or without tracking). 
                    Learn more in the [Card Delivery Method](/guide/cards/creation.html#card-delivery-method-deliverymethod) article.
                pinMailer:
                  type: integer
                  description: |
                    You can request the card manufacturer to send the card PIN code by letter.
                    Learn more in the [Pin Mailer](/guide/cards/creation.html#pin-mailer-pinmailer) article.
                  enum: [0,1]
                customizedInfo:
                  type: string
                  maxLength: 27
                  description: |
                    Customized text to be displayed on the card.

                    If populated, it must: 
                    * Be alphanumeric
                    * Contain at most 27 characters
                    * Not contain `!"#%'(),:;<>?@[]^` or the backtick symbol.
                freeCustomizedInfo:
                  type: string
                  maxLength: 50
                  description: |
                    More customized text to be displayed on the card.

                    If populated, it must: 
                    * Be alphanumeric
                    * Contain at most 50 characters
                    * Not contain `!"#%'(),:;<>?@[]^` or the backtick symbol.
                letterCustomizedInfo:
                  type: string
                  maxLength: 50
                  description: |
                    Customized text for the letter that is joined to the card.

                    If populated, it must:
                    * Be alphanumeric
                    * Contain at most 50 characters
                    * Not contain `!"#%'(),:;<>?@[]^` or the backtick symbol.
                cardLanguages:
                  type: string
                  maxLength: 8
                  format: ISO 639-1 alpha-2
                  description: |
                    The language preferences for the card for [ATMs](/guide/overview/glossary.html#automated-teller-machine-atm), in the order of preference. For instance, for French and English, you have to enter "fren".

                    While this information is well taken into account in the card configuration, please note that the API will not return the value.
                    
                    Must be alphabetic and max. 8 characters. Format: [ISO 639-1-alpha2](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).
                  example: "fren"
                  nullable: true
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/CardObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/cards/Register3DS:
    post:
      tags:
        - Cards
      summary: Register 3D secure
      operationId: post3ds
      description: |
        Register a card for 3D secure authentication. The user's mobile number must begin with `+`, or `00`, and the country dialing code.

        This includes an **optional fallback** with a one-time password (OTP) sent by SMS; the card must be enrolled for Out of Band (OOB) authentication.
        Learn more in the [SCA for Card Transactions](/guide/strong-customer-authentication/securing-endpoints.html#sca-for-card-transactions) article.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`card.register3DS`](/guide/cards/events.html#card-register3ds) |
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - cardId
              type: object
              properties:
                cardId:
                  type: integer
                  description: The unique identifier of the card.
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
               $ref: '#/components/schemas/CardObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/cardimages:
    get:
      tags:
        - Cards
      summary: Get Card Image
      description: | 
        Retrieve a virtual card image.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-operation |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getCardImage
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: cardId
          in: query
          description: The unique identifier of the virtual card.
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                type: object
                properties:
                  cardimages:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: The unique identifier of the Card Image.
                        cardId:
                          type: string
                          description: The unique identifier of the Card.
                        file:
                          type: string
                          format: byte
                          description: | 
                            The image of the Card.

                            Pattern: `^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$`
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/cards/{cardId}/Activate:
    put:
      tags:
        - Cards
      summary: Activate Card
      operationId: activateCard
      description: |
        Activate the Card (updating the `isLive` attribute to `1`). A Card must be activated to be used.

        See also [`PUT /v1/cards/{cardToken}/public-token-activation`](/api-reference/api-endpoints.html#tag/Cards/activateCardToken) for end user-oriented activation.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-operation |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`card.activate`](/guide/cards/events.html#card-activate) |
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: path
          description: The unique identifier of the Card.
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/CardObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/cards/{cardToken}/public-token-activation:
    put:
      tags:
        - Cards
      summary: Activate Card Public Token
      operationId: activateCardToken
      description: |
        Activate the Card (updating the `isLive` attribute to `1`). A Card must be activated to be used.
        
        Ideal for end user-oriented action. For machine-oriented action, see [`PUT /v1/cards/{cardId}/Activate`](/api-reference/api-endpoints.html#tag/Cards/activateCard).

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-operation |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`card.activate`](/guide/cards/events.html#card-activate) |
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: cardToken
          in: path
          description: The `publicToken` of the Card.
          required: true
          schema:
            type: string
            example: "12345"
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/CardObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/cards/{cardId}/Assign:
    put:
      tags:
        - Cards
      summary: Reassign Card
      operationId: reassignCard
      description: |
        Assign the Card to another User or Wallet.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`card.update`](/guide/cards/events.html#card-update) |
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: path
          description: The unique identifier of the Card to reassign.
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: integer
                  description: |
                    `userId` and `walletId` can both be provided. `userId` is mandatory if `walletId` is not provided.
                walletId:
                  type: integer
                  description: |
                    `userId` and `walletId` can both be provided. `walletId` is mandatory if `userId` is not provided.
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/CardObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/cards/{cardId}/assignWallet:
    put:
      tags:
        - Cards
      summary: Assign Wallet
      operationId: assignCardWallet
      description: |
        Assign the Card to another Wallet.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write`, `legal` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`card.assignWallet`](/guide/cards/events.html#card-assignwallet) |
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: path
          description: The unique identifier of the Card to reassign.
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              required:
                - walletId
              type: object
              properties:
                walletId:
                  type: integer
                  description: |
                    The unique identifier of the Wallet to which the Card is to be assigned.
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/CardObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - legal
          - admin
          - read_write
  /v1/cards/{cardId}/ChangePIN:
    put:
      tags:
        - Cards
      summary: Change Card PIN
      operationId: changePin
      description: | 
        Change the Card PIN code knowing the current one.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-operation |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`card.changepin`](/guide/cards/events.html#card-changepin) |
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: path
          description: The unique identifier of the Card.
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              required:
                - currentPIN
                - newPIN
                - confirmPIN
              type: object
              properties:
                currentPIN:
                  type: string
                  description: The current PIN code of the card.
                newPIN:
                  type: string
                  description: The new PIN code of the card.
                confirmPIN:
                  type: string
                  description: The confirmation of the new PIN code of the card.              
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/CardObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/cards/{cardId}/ConvertVirtual:
    put:
      tags:
        - Cards
      summary: Convert virtual card to physical
      operationId: convertVirtual
      description: |
        Convert a virtual Card into a physical one. The converted card will be both virtual and physical.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`card.convertvirtual`](/guide/cards/events.html#card-convertvirtual) |
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: path
          description: The unique identifier of the Card to convert.
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              properties:              
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/CardObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/cards/{cardId}/Limits:
    put:
      tags:
        - Cards
      summary: Update Card Limits
      operationId: putLimits
      description: | 
        Modify the Card limits.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-operation |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`card.limits`](/guide/cards/events.html#card-limits) |
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: path
          description: The unique identifier of the Card.
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                limitAtmYear:
                  type: integer
                  description: ATM operations limit for a sliding year. No default value.
                limitAtmMonth:
                  type: integer
                  description: ATM operations limit for a sliding month. No default value.
                limitAtmWeek:
                  type: integer
                  description: ATM operations limit for a sliding week. Default value €2000.
                limitAtmDay:
                  type: integer
                  description: ATM operations limit for a single day. Default value €1000.
                limitAtmAll:
                  type: integer
                  description: ATM operations limit from beginning. No default value.
                limitPaymentYear:
                  type: integer
                  description: POS operations limit for a sliding year. No default value.
                limitPaymentMonth:
                  type: integer
                  description: POS operations limit for a sliding month. No default value.
                limitPaymentWeek:
                  type: integer
                  description: POS operations limit for a sliding week. Default value €3000.
                limitPaymentDay:
                  type: integer
                  description: POS operations limit for a single day. Default value €2000.
                limitPaymentAll:
                  type: integer
                  description: POS operations limit from beginning. No default value.
                paymentDailyLimit:
                  type: number
                  format: float
                  description: POS operations limit for a single day including cents. The decimal delimiter must be ".". No default value.
                restrictionGroupLimits:
                  type: object
                  properties:
                    mccRestrictionGroups:
                      type: array
                      minItems: 1
                      uniqueItems: true
                      items:
                        type: integer
                        format: int64
                      description: List of MCC (Merchant Category Code) Restriction Groups.
                    countryRestrictionGroups:
                      type: array
                      minItems: 1
                      uniqueItems: true
                      items:
                        type: integer
                        format: int64
                      description: List of Country Restriction Groups.
                    merchantIdRestrictionGroups:
                      type: array
                      minItems: 1
                      uniqueItems: true
                      items:
                        type: integer
                        format: int64
                      description: List of Merchant ID Restriction Groups.
                  required:
                    - mccRestrictionGroups
                    - countryRestrictionGroups
                    - merchantIdRestrictionGroups
                  description: |
                    Group of limits based on Restriction Groups. For now, only Restaurant Payment Vouchers with `paymentDailyLimit` can use this field.
                    Furthermore, one of `mccRestrictionGroups`, `countryRestrictionGroups` or `merchantIdRestrictionGroups` must bepresent (i.e., `paymentDailyLimit` can't be alone).
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/CardObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/cards/{cardId}/LockUnlock:
    put:
      tags:
        - Cards
      summary: Update Card Lock Status
      operationId: updateBlockStatus
      description: | 
        Block or unblock a card.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-operation |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`card.lockunlock`](/guide/cards/events.html#card-lockunlock) |
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: path
          description: The unique identifier of the Card.
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              required:
                - lockStatus
              type: object
              properties:
                lockStatus:
                  type: integer
                  description: |
                    The Status of the card, indicating whether it is locked, lost, or destroyed.

                    While this field is an integer, it returns a plaintext value. See the full list of `lockStatus` in the [Block a Card](/guide/cards/modification.html#status) article.
                  enum: [0,1,2,3,4,5,7]
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/CardObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/cards/{cardId}/Options:
    put:
      tags:
        - Cards
      summary: Update Card Options
      description: | 
        Modify the Card permissions group.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-operation |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`card.options`](/guide/cards/events.html#card-options) |
      operationId: cardOptions
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: path
          description: The unique identifier of the Card.
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              required:
                - nfc
                - foreign
                - online
                - atm
              type: object
              properties:
                foreign:
                  type: integer
                  description: | 
                    Whether the card is usable abroad. See [Options & Permission groups](/guide/cards/restrictions-limits.html#options-permission-groups) for more information.
                  enum: [0,1]
                online:
                  type: integer
                  description: | 
                    Whether the card is usable online. See [Options & Permission groups](/guide/cards/restrictions-limits.html#options-permission-groups) for more information.
                  enum: [0,1]
                atm:
                  type: integer
                  description: | 
                    Whether the card is usable on ATMs (withdrawal). See [Options & Permission groups](/guide/cards/restrictions-limits.html#options-permission-groups) for more information.
                  enum: [0,1]
                nfc:
                  type: integer
                  description: | 
                    Whether the card can be used for contactless payments. See [Options & Permission groups](/guide/cards/restrictions-limits.html#options-permission-groups) for more information.
                  enum: [0,1]
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/CardObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/cards/{cardId}/Regenerate:
    put:
      tags:
        - Cards
      summary: Regenerate Card
      operationId: regenerateCard
      description: |
        Recreate the card image if the card is unlocked. 
        
        Useful when changing card design, company name, or when retrieving the image results in a 404.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`card.regenerate`](/guide/cards/events.html#card-regenerate) |
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: path
          description: The unique identifier of the Card.
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              properties:              
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/CardObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/cards/{cardId}/setPIN:
    put:
      tags:
        - Cards
      summary: Set Card PIN
      operationId: setPin
      description: | 
        Overwrite the Card PIN code.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-operation |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`card.setpin`](/guide/cards/events.html#card-setpin) |
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: path
          description: The unique identifier of the Card.
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              required:
                - newPIN
                - confirmPIN
              properties:              
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                newPIN:
                  type: string
                  description: The new PIN code of the card.
                confirmPIN:
                  type: string
                  description: Confirmation of the value of the new PIN code of the card.
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/CardObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/cards/{cardId}/UnblockPIN:
    put:
      tags:
        - Cards
      summary: Unblock Card PIN
      description: | 
        Unblock the Card PIN code.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-operation |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`card.unblockpin`](/guide/cards/events.html#card-unblockpin) |
      operationId: unblockPin
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: path
          description: The unique identifier of the Card.
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              properties:              
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/CardObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/cards/{cardId}/unblockcvc2:
    put:
      tags:
        - Cards
      summary: Unblock Card CVC2 
      operationId: unblockCvc
      description: |
        Unblock a Card whose CVC2 is locked.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-operation |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`card.unblockcvc2`](/guide/cards/events.html#card-unblockcvc2) |
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: path
          description: The unique identifier of the Card.
          required: true
          schema:
            type: integer
            example: 12345
      responses:
        '204':
          description: successfully unblocked.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2: []
  /v1/cards/{cardId}/authentication-methods:
    get:
      tags:
        - Card 3DSecure Enrollment (SCA)
      summary: Get Authentication Methods
      operationId: getAuthMethods
      description: | 
        Retrieve the authentication methods of a Card.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | N/A |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: path
          description: The unique identifier of the Card.
          required: true 
          schema:
            type: string
            example: "12345"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  publicToken:
                    type: string
                    description: The public token of the Card
                  id:
                    type: string
                    format: uuid
                    description: The unique identifier of the authentication method.
                    example: "8a451234-a8a0-4c54-9fbe-b5212344afb3"
                  method:
                    type: string
                    description: The method used, either `OOB` or `OTPSMS`
                    enum: ["OOB", "OTPSMS"]
                  system:
                    type: string
                    description: The ACS (Access Control Server) provider.
                    deprecated: true
                    enum: ["GPS"]
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2: []
    post:
      tags:
        - Card 3DSecure Enrollment (SCA)
      summary: Create Authentication Methods
      operationId: postAuthMethods
      description: | 
        Define the authentication method of a Card.

        This is the **primary and mandatory** strong customer authentication of the cardholder through their payment application. Card must also be registered for 3DS as an **optional fallback** authentication.
        Learn more in the [SCA for Card Transactions](/guide/strong-customer-authentication/securing-endpoints.html#sca-for-card-transactions) article.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | N/A |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: path
          description: The unique identifier of the Card.
          required: true 
          schema:
            type: string
            example: "12345"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                method:
                  type: string
                  description: The authentication method.
                  default: 'OOB'
                  enum: ["OOB", "OTPSMS"]
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  publicToken:
                    type: string
                    description: The public token of the Card
                  id:
                    type: string
                    format: uuid
                    description: The unique identifier of the authentication method.
                    example: "8a451234-a8a0-4c54-9fbe-b5212344afb3"
                  method:
                    type: string
                    description: The method used, either `OOB` or `OTPSMS`
                    enum: ["OOB", "OTPSMS"]
                  system:
                    type: string
                    description: The ACS (Access Control Server) provider.
                    deprecated: true
                    enum: ["GPS"]
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2: []
  /v1/cards/{cardId}/authentication-methods/{methodId}:
    get:
      tags:
          - Card 3DSecure Enrollment (SCA)
      summary: Get Authentication Method
      description: |
        Retrieve details regarding the authentication method of a Card.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | N/A |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getAuthMethodsDetails
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: path
          description: The unique identifier of the Card.
          required: true
          schema:
            type: string
            example: "12345"
        - name: methodId
          in: path
          description: The unique identifier of the authentication method.
          required: true
          schema:
            type: string
            example: "12345"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  publicToken:
                    type: string
                    description: The public token of the Card
                  id:
                    type: string
                    format: uuid
                    description: The unique identifier of the authentication method.
                    example: "8a451234-a8a0-4c54-9fbe-b5212344afb3"
                  method:
                    type: string
                    description: The method used, either `OOB` or `OTPSMS`
                    enum: ["OOB", "OTPSMS"]
                  system:
                    type: string
                    description: The ACS (Access Control Server) provider.
                    deprecated: true
                    enum: ["GPS"]
        '400':
          description: Unknown card ID
          content: { }
        '404':
          description: Auth method not found
          content: { }
        '500':
          description: Internal server error
          content: { }
      security:
        - OAuth2: []
    delete:
      tags:
        - Card 3DSecure Enrollment (SCA)
      summary: Delete Authentication Method
      description: | 
        Delete the authentication method of a Card. Only available for OOB method.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | N/A |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: deleteAuthMethods
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: path
          description: The unique identifier of the Card.
          required: true
          schema:
            type: string
            example: "12345"
        - name: methodId
          in: path
          description: The unique identifier of the authentication method.
          required: true
          schema:
            type: string
            example: "12345"
      responses:
        '204':
          description: The auth method has been removed
          content: { }
        '400':
          description: Unknown card ID
          content: { }
        '404':
          description: Auth method not found
          content: { }
        '500':
          description: Internal server error
          content: { }
      security:
        - OAuth2: []

  /v1/auth-requests/{authRequestId}/result:
    put:
      tags:
        - Card Transactions Authentication (SCA)
      summary: Submit Authentication Request Result
      description: | 
        Submit the result of an authentication request.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | N/A |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-operation |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`card3DSv2Authentication.update`](/guide/cards/events-tx.html#card3DSv2authentication-update) |
      operationId: putAuthRequestResult
      parameters:
       #- $ref: '#/components/parameters/Authorization'
        - name: authRequestId
          in: path
          description: The unique identifier of an authentication.
          required: true
          schema:
            type: string
            format: uuid
            example: cbc7944f-ff75-4e6c-877c-34e373042d40
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - authenticationResult
              properties:
                authenticationResult:
                  type: string
                  description: The authentication result.
                  enum: [ "OK", "KO_TECHNICAL", "KO_AUTH_FAILED", "FALLBACK" ]
      responses:
        '200':
          description: Authentication result submitted successfully.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2: []
  /simulation/auth-requests:
    post:
      tags:
        - Card Transactions Authentication (SCA)
      summary: Simulate Authentication Request
      description: |
        Create a simulation of an SCA authentication for an online card transaction, as if it was sent by the ACS provider. Endpoint available in Sandbox only.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | N/A |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`card3DSv2Authentication.create`](/guide/cards/events-tx.html#card3DSv2authentication-create) |
      operationId: simulateAuthRequest
     # parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - cardId
                - merchantName
                - paymentAmount
                - paymentCurrency
              properties:
                cardId:
                  type: integer
                  example: 60001
                  description: The unique identifier of the Card.
                merchantName:
                  type: string
                  example: 'Apple Inc.'
                  description: The name of the merchant processing the transaction for the simulated authentication.
                paymentAmount:
                  type: number
                  format: float
                  example: 10.01
                  description: The amount of the transaction for the simulated authentication.
                paymentCurrency:
                  type: string
                  format: ISO 4217
                  description: The currency of the transaction for the simulated authentication.
                  example: 'EUR'
                merchantAppRedirectURL:
                  type: string
                  example: 'https://your.app.com/redirect'
                  description: The `merchantAppRedirectURL` as defined in the 3DS 2.2 specification. Used to link back to the merchant application from an OOB app.
      responses:
        '204':
          description: Created
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2: []

  /simulation/authrequests/{authRequestId}/cancel:
    post:
      tags:
        - Card Transactions Authentication (SCA)
      summary: Simulate Canceled Authentication Request
      description: |
        When a simulated authentication is in progress, you can simulate a cancellation (e.g. if the cardholder closes their web browser or application). Endpoint available in Sandbox only.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | N/A |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: simulateAuthRequestCancel
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: authRequestId
          in: path
          description: The unique identifier of an authentication.
          required: true
          schema:
            type: string
            format: uuid
            example: cbc7944f-ff75-4e6c-877c-34e373042d40
      responses:
        '204':
          description: Authentication result submitted successfully.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2: []

  /v1/cards/{cardId}/renewalDetails:
    get:
      tags:
        - Cards
      summary: Get Renewal Details
      operationId: getRenewalDetails
      description: |
        Retrieve the Card `renewalType`.
        
        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write`, `legal` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: path
          description: The unique identifier of the Card.
          required: true
          schema:
            type: integer
            example: 12345
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  cardRenewalDetails:
                    type: object
                    properties:
                      renewalType:
                        type: string
                        description: |
                          The type of renewal for the card. Can be:

                          * `A` – Automatic
                          * `N` – Non automatic
                        example: "A"
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
          - admin
          - legal
    put:
      tags:
        - Cards
      summary: Update Renewal Details
      operationId: updateRenewalDetails
      description: |
        Update the Card `renewalType`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write`, `legal` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: path
          description: The unique identifier of the Card.
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                embossLegalName:
                  type: boolean
                  description: |
                    When set to `true`, embosses the corresponding user's `legalName` on the card. See the [embossed name](/guide/cards/creation.html#embossed-name-embossedname) article for more information.

                    Depending on the configuration, the legal name may be displayed regardless of the value of this field.
                  default: false
                logoId:
                  type: string
                  maxLength: 30
                  description: |
                    The file name of the logo for the card, as uploaded to the manufacturer. Learn more in the [Logo](/guide/cards/creation.html#logo-logoid) article.
                  example: "MyLogoFile.png"
                logoBackId:
                  type: string
                  description: |
                    The file name of the logo for the back of the card, as uploaded to the manufacturer. Learn more in the [Back Logo](/guide/cards/creation.html#back-logo-logobackid) article.
                  maxLength: 30
                  example: "MyBackLogoFile.png"
                customizedInfo:
                  type: string
                  maxLength: 27
                  description: |
                    Customized text to be displayed on the card.

                    If populated, it must: 
                    * Be alphanumeric
                    * Contain at most 27 characters
                    * Not contain `!"#%'(),:;<>?@[]^` or the backtick symbol.
                freeCustomizedInfo:
                  type: string
                  maxLength: 50
                  description: |
                    More customized text to be displayed on the card.

                    If populated, it must: 
                    * Be alphanumeric
                    * Contain at most 50 characters
                    * Not contain `!"#%'(),:;<>?@[]^` or the backtick symbol.
                letterCustomizedInfo:
                  type: string
                  maxLength: 50
                  description: |
                    Customized text for the letter that is joined to the card.

                    If populated, it must:
                    * Be alphanumeric
                    * Contain at most 50 characters
                    * Not contain `!"#%'(),:;<>?@[]^` or the backtick symbol.
                designCode:
                  type: string
                  maxLength: 2
                  description: |
                    Customization code for the card design. If missing, falls back to the default Design Code. Learn more in the [Designs](/guide/cards/creation.html#designs-designcode) article.
                  format: alphanumeric
                packageId:
                  type: string
                  maxLength: 8
                  description: Packaging reference for card shipping. Max. 8 characters.
                  example: "Pkg123"
                sendToParent:
                  type: integer
                  description: | 
                    Whether the card should be sent to the cardholder's Parent User. 

                    When set to `1`, the delivery address fields will be automatically filled in with the parent user's address.
                  enum: [0,1]
                deliveryMethod:
                  type: integer
                  description: | 
                    The method the manufacturer uses to send the cards (e.g., delivery with or without tracking). 
                    Learn more in the [Card Delivery Method](/guide/cards/creation.html#card-delivery-method-deliverymethod) article.
                renewalType:
                  type: string
                  description: |
                    The type of renewal for the card. Can be:

                    * `A` – Automatic
                    * `N` – Non automatic
                  enum: [ "A", "N" ]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  cardRenewalDetails:
                    type: object
                    properties:
                      renewalType:
                        type: string
                        description: |
                          The type of renewal for the card. Can be:

                          * `A` – Automatic
                          * `N` – Non automatic
                        example: "A"
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
          - admin
          - legal
  /v1/cards/{cardId}/renew:
    put:
      tags:
        - Cards
      summary: Renew Card
      operationId: putRenew
      description: |
        Renew a Card manually. This is only possible for active cards that haven't been renewed yet, and whose status is `UNLOCK`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write`, `legal` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`card.renew`](/guide/cards/events.html#card-renew) |
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: cardId
          in: path
          description: The unique identifier of the Card.
          required: true
          schema:
            type: integer
            example: 12345
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/CardObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
          - admin
          - legal

  /v1/bulk-updates/cardLimits:
    post:
      summary: Create Card Limits Bulk Update
      operationId: createBulkCardUpdate
      tags:
        - Card Bulk Updates
      description: |
        Create a Card bulk update to update the card limits for multiple cards.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` | 
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** |  [`cardBulkUpdate.create`](/guide/cards/events.html#cardbulkupdate-create) |
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - cardIds
                - cardAttributes
              type: object
              properties:
                cardIds:
                  description: |
                    The list of cards to update.
                  type: array
                  items:
                    type: integer
                    description: The unique identifier of the Card.
                    example: 12345
                bulkUpdateTag:
                  description: The name of the bulk update request.
                  type: string
                  example: "new contract limits May 2025"
                  maxLength: 250
                cardAttributes:
                  description: The attributes of the cards that can be updated.
                  type: object
                  properties:
                    limitAtmYear:
                      type: integer
                      nullable: true
                      description: |
                        ATM operations limit of the card for a sliding year.

                        See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                      example: 2000
                    limitAtmMonth:
                      type: integer
                      nullable: true
                      description: |
                        ATM operations limit of the card for a sliding month.

                        See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                      example: 2000
                    limitAtmWeek:
                      type: integer
                      nullable: true
                      description: |
                        ATM operations limit of the card for a sliding week.

                        See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                      example: 2000
                    limitAtmDay:
                      type: integer
                      nullable: true
                      description: |
                        ATM operations limit of the card for a single day.

                        See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                      example: 2000
                    limitAtmAll:
                      type: integer
                      nullable: true
                      description: |
                        ATM operations limit of the card from beginning.

                        See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                    limitPaymentYear:
                      type: integer
                      nullable: true
                      description: |
                        POS operations limit of the card for a sliding year.

                        See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                      example: 5000
                    limitPaymentMonth:
                      type: integer
                      nullable: true
                      description: |
                        POS operations limit of the card for a sliding month.

                        See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                      example: 2000
                    limitPaymentWeek:
                      type: integer
                      nullable: true
                      description: |
                        POS operations limit of the card for a sliding week.

                        See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                      example: 2000
                    limitPaymentDay:
                      type: integer
                      nullable: true
                      description: |
                        POS operations limit of the card for a single day.

                        See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                      example: 2000
                    limitPaymentAll:
                      type: integer
                      nullable: true
                      description: |
                        POS operations limit of the card from the beginning.

                        See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                    paymentDailyLimit:
                      type: number
                      format: float
                      nullable: true
                      description: |
                        POS operations limit of the card for a single day, including cents.

                        For food vouchers use cases only.
                      example: 25.55
                    restrictionGroupLimits:
                      type: array
                      items:
                        type: object
                        properties:
                          paymentDailyLimit:
                            type: number
                            format: float
                            minimum: 0
                            exclusiveMinimum: true
                          mccRestrictionGroups:
                            type: integer
                            format: int64
                            minimum: 0
                            exclusiveMinimum: true
                          countryRestrictionGroups:
                            type: integer
                            format: int64
                            minimum: 0
                            exclusiveMinimum: true
                          merchantIdRestrictionGroups:
                            type: integer
                            format: int64
                            minimum: 0
                            exclusiveMinimum: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUpdateObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/bulk-updates/{bulkUpdateId}:
    get:
      summary: Get Card Bulk Update
      operationId: getBulkCardUpdate
      tags:
        - Card Bulk Updates
      description: |
        Retrieve a Card bulk update based on its `id`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` | 
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** |  N/A |
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: bulkUpdateId
          description: The unique identifier of the bulk update.
          in: path
          schema:
            type: string
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUpdateObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2: 
          - read_only
  /bulk-updates:
    get:
      summary: Get Card Bulk Updates
      operationId: listBulkCardUpdates
      tags:
        - Card Bulk Updates
      description: |
        Retrieve the list of Card bulk updates.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` | 
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: bulkUpdateTag
          in: query
          description: The name of the bulk update request.
          schema:
            type: string
        - name: bulkProgressStatus
          in: query
          description: Bulk update progress status.
          schema:
            type: string
            enum: ["IN_PROGRESS","DONE","FAILED"]
        - name: bulkType
          in: query
          description: Bulk update type.
          schema:
            type: string
            enum: ["CARD_LIMITS"]
        - name: cursor
          in: query
          description: Pagination cursor, if you don't pass a cursor, result will start at the first page.
          schema:
            type: string
            example: "da4b9237bacccdf19c0760cab7aec4a8359010b0"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  bulks:
                    type: array
                    items:
                      $ref: '#/components/schemas/BulkUpdateObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only

  /v1/cards/{cardId}/digitalizedCards:
    get:
      security:
        - OAuth2:
          - read_only
      description: |
        Retrieve the list of Digitized Cards for a given `cardId`.
      summary: Get Digitized Cards
      operationId: getDigitalized
      tags: 
        - Digitized Cards
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: cardId
          description: The unique identifier of the virtual or physical card.
          schema:
            type: string
            example: "12345"
          in: path
          required: true
      responses:
        '200':
          description: List successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDigitalizedCardResponse'
        '400':
          $ref: '#/components/responses/DigitalizedCardsBadRequest'
        '401':
          $ref: '#/components/responses/DigitalizedCardsUnauthorizedError'
        '404':
          $ref: '#/components/responses/DigitalizedCardsNotFound'
        '500':
          $ref: '#/components/responses/DigitalizedCardsInternalError'
  
  /v1/cards/digitalizedCards/{id}:
    put:
      security:
        - OAuth2:
          - read_write
      description: |
        Update the status of a payment Token.
      summary: Update Payment Token Status
      operationId: putDigitalized
      tags: 
        - Digitized Cards
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: id
          description: |
            The unique identifier of a digitized card. 
            
            You can find this value in:
            * The `GET /v1/cards/{cardId}/digitalizedCards` endpoint, `id` field, or
            * The [`cardDigitalization.complete`](/guide/cards/events.html#carddigitalization-complete) webhook, `object_id`.
          schema:
            type: integer
            format: int64
            example: 12345
          in: path
          required: true
      requestBody:
        content:
          application/json:
            schema:
              required:
                - reasonCode
                - status
              type: object
              properties:
                status:
                  type: string
                  description: |
                    The new status for the payment Token.
                  enum: [suspend, unsuspend]
                reasonCode:
                  description: |
                    The reason code for the action. See the [corresponding article](/guide/cards/x-pay-google-apple.html#parameters) for the definition of each value.
                  type: string
                  enum: [F, L, S, T, Z]
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DigitizedCardResponse'
        '400':
          $ref: '#/components/responses/DigitalizedCardsBadRequest'
        '401':
          $ref: '#/components/responses/DigitalizedCardsUnauthorizedError'
        '404':
          $ref: '#/components/responses/DigitalizedCardsNotFound'
        '500':
          $ref: '#/components/responses/DigitalizedCardsInternalError'
    delete:
      security:
        - OAuth2:
          - read_write
      description: |
        Deactivate a payment Token.
      summary: Deactivate Payment Token
      operationId: deleteDigitalized
      tags: 
        - Digitized Cards
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: id
          description: |
            The unique identifier of a digitized card. 
            
            You can find this value in:
            * The `GET /v1/cards/{cardId}/digitalizedCards` endpoint, `id` field, or
            * The [`cardDigitalization.complete`](/guide/cards/events.html#carddigitalization-complete) webhook, `object_id`.
          schema:
            type: integer
            format: int64
            example: 12345
          in: path
          required: true
        - in: query
          name: reasonCode
          description: | 
            The reason code is required only if the card is on Mastercard System. Possible values are:

            | Reason code | Description |
            | :----: | ----------- |
            | C | Account closed |
            | D | Issuer consumer deleted |
            | F | Cardholder reported token device found or not stolen |
            | L | Cardholder confirmed token device lost |
            | S | Cardholder confirmed token device stolen |
            | T | Issuer or cardholder confirmed fraudulent token transactions |
            | Z | Other |
          schema:
            type: string
            enum: [ C, D, F, L, S, T, Z ]
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DigitizedCardResponse'
        '400':
          $ref: '#/components/responses/DigitalizedCardsBadRequest'
        '401':
          $ref: '#/components/responses/DigitalizedCardsUnauthorizedError'
        '404':
          $ref: '#/components/responses/DigitalizedCardsNotFound'
        '500':
          $ref: '#/components/responses/DigitalizedCardsInternalError'
    get:
      security:
        - OAuth2:
          - read_only
      description: Retrieve a payment token.
      summary: Get Payment Token
      operationId: getPaymentToken
      tags: 
        - Digitized Cards
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: id
          description: |
            The unique identifier of a digitized card.

            You can find this value in:
            * The `GET /v1/cards/{cardId}/digitalizedCards` endpoint, `id` field, or
            * The [`cardDigitalization.complete`](/guide/cards/events.html#carddigitalization-complete) webhook, `object_id`.
          schema:
            type: integer
            format: int64
            example: 12345
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDigitalizedCardResponse'
        '400':
          $ref: '#/components/responses/DigitalizedCardsBadRequest'
        '401':
          $ref: '#/components/responses/DigitalizedCardsUnauthorizedError'
        '404':
          $ref: '#/components/responses/DigitalizedCardsNotFound'
        '500':
          $ref: '#/components/responses/DigitalizedCardsInternalError'
  
  /v1/cardtransactions:
    get:
      tags:
        - Card Transactions
      summary: Search Card Transactions
      description: |
        Retrieve Card Transactions based at least on one of the following inputs: `cardId`, `paymentId`, `publicToken`, `walletId`. This is the preferred request for end user-oriented usage.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: readCardTransaction
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: cardtransactionId
          in: query
          description: The unique identifier of the Card Transaction.
          schema:
            type: integer
            example: 12345
        - name: cardId
          in: query
          description: The unique identifier of the Card.
          schema:
            type: integer
            example: 12345
        - name: walletId
          in: query
          description: The unique identifier of the Wallet the card is attached to.
          schema:
            type: integer
            example: 12345
        - name: merchantId
          in: query
          description: The Merchant's Id.
          schema:
            type: string
        - name: publicToken
          in: query
          description: The public token of the Card.
          schema:
            type: string
        - name: paymentId
          in: query
          description: The unique identifier of the card payment (or attempted payment), allowing you to follow the card transaction life cycle.
          schema:
            type: integer
            example: 12345
        - name: pageNumber
          in: query
          description: |
            The page number, only available on /v1/ endpoints 
          schema:
            type: integer
        - name: pageCount
          in: query
          description: |
            The number of items per page, only available on /v1/ endpoints  
          schema:
            type: integer
        - name: sortBy
          in: query
          description: |
            The transaction element you want to sort the list with.
          schema:
            type: string
            default: "createdDate"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  cardtransactions:
                    type: array
                    items:
                      $ref: '#/components/schemas/CardTransactionObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
  /v1/cardtransactions/{cardtransactionId}:
    get:
      tags:
        - Card Transactions
      summary: Get Card Transaction
      description: | 
        Retrieve a Card Transaction based on its `id`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getCardtransaction
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: cardtransactionId
          in: path
          description: The unique identifier of the Card Transaction.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  cardtransactions:
                    type: array
                    items:
                      $ref: '#/components/schemas/CardTransactionObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
          - read_only
  /v1/countryRestrictionGroups:
    get:
      tags:
        - Country Restriction Groups
      summary: Search Country Restriction Groups
      description: | 
        Retrieve country restriction groups that match search criteria.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getCountryRestrictionGroups
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: fields
          in: query
          description: List of the object properties to be returned, allowing you to filter the response payload.
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: filter
          in: query
          description: |
            You can filter the API response by using filter(s).
            Filterable fields are:
              - id
              - name
              - isWhitelist
              - status
              - startDate
              - createdDate

            Filters should be separated by a ";". Example for 3 filters: FILTER1;FILTER2;FILTER3.

            A single filter has the following syntax: "fieldName criterion expression", where:
              - fieldName: the name of a filterable field of this object.
              - expression: the values to be included or excluded (see the table below for more information)
              - criterion: a filter criterion.

            Here are the possible values for criterion:

            | Criteria |         Description    |                   Type                   | Expression Example |
            |----------|------------------------|------------------------------------------|--------------------|
            |     >    |      greater than      |            alphanumeric string           |         100        |
            |    >=    | greater or equal than  |            alphanumeric string           |         100        |
            |     <    |        less than       |            alphanumeric string           |         100        |
            |    <=    |   less or equal than   |            alphanumeric string           |         100        |
            |    !=    |      not equal to      |            alphanumeric string           |         100        |
            |   like   |          like          |            alphanumeric string           |         100        |
            |    in    |           in           | alphanumeric strings separated by commas |      100,30,25     |
            |    ==    |         equals         |            alphanumeric string           |         100        |
          schema:
            type: string
        - name: pageNumber
          in: query
          description: |
            The page number, only available on /v1/ endpoints 
          schema:
            type: integer
        - name: pageCount
          in: query
          description: |
            The number of items per page, only available on /v1/ endpoints  
          schema:
            type: integer
        - name: sortBy
          in: query
          description: |
            The transaction element you want to sort the list with.
          schema:
            type: string
            default: createdDate
        - name: sortOrder
          in: query
          description: |
            The order you want to sort the list.
          schema:
            type: string
            default: DESC
            enum:
              - ASC
              - DESC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  countryRestrictionGroups:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: The unique identifier of the Country Group.
                        name:
                          type: string
                          description: The name the Country Group.
                        isWhitelist:
                          type: boolean
                          description: |
                            Indicates the kind of restriction:
                             * `true` (default) – Allows only a specified list of countries (whitelist)
                             * `false` – Allows all countries except the specified list (blacklist)
                          default: true
                        countries:
                          type: array
                          description: The list of countries.
                          items:
                            type: string
                            description: |
                              The country in [ISO 3166-1 numeric format (a 3-digit code)](https://en.wikipedia.org/wiki/ISO_3166-1_numeric).
                            format: ISO 3166-1
                            example: "250"
                        status:
                          type: string
                          description: The status of the Country Group.
                          enum:
                            - CANCELED
                            - PENDING
                            - VALIDATED
                        startDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: |
                            The date and time at which the restriction starts.

                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2024-04-24 08:55:26"
                        createdDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: |
                            The date and time at which the restriction group was created.

                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2024-04-24 08:55:26"
                        modifiedDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: |
                            The date and time at which the restriction group was last updated. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2025-02-12 12:45:23"
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    post:
      tags:
        - Country Restriction Groups
      summary: Create Country Restriction Group
      description: |
        Create a new country restriction group.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`countryGroup.create`](/guide/cards/events.html#countrygroup-create) |
      operationId: postCountryRestrictionGroup
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - countries
                - name
              type: object
              properties:
                name:
                  type: string
                  description: The name of the Country Group.
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                status:
                  type: string
                  description: The status of the Country Group.
                  default: "PENDING"
                  enum:
                    - CANCELED
                    - PENDING
                    - VALIDATED
                isWhitelist:
                  type: boolean
                  description: |
                    Indicates the kind of restriction: 
                      * `true` (default) – Allows only a specified list of countries (whitelist)
                      * `false` – Allows all countries except the specified list (blacklist)
                  default: true
                countries:
                  type: array
                  description: The list of countries.
                  items:
                    type: string
                    description: |
                      The country in [ISO 3166-1 numeric format (a 3-digit code)](https://en.wikipedia.org/wiki/ISO_3166-1_numeric).
                    format: ISO 3166-1
                    example: "250"
                startDate:
                  type: string
                  # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                  description: | 
                    The date and time at which the restriction starts. 
                    
                    Format: `YYYY-MM-DD HH:mm:ss`
                  example: "2024-04-24 08:55:26"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  countryRestrictionGroups:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: The unique identifier of the Country Group.
                        name:
                          type: string
                          description: The name of the Country Group.
                        isWhitelist:
                          type: boolean
                          description: |
                            Indicates the kind of restriction: 
                             * `true` (default) – Allows only a specified list of countries (whitelist)
                             * `false` – Allows all countries except the specified list (blacklist)
                          default: true
                        countries:
                          type: array
                          description: The list of countries.
                          items:
                            type: string
                            description: |
                              The country in [ISO 3166-1 numeric format (a 3-digit code)](https://en.wikipedia.org/wiki/ISO_3166-1_numeric).
                            format: ISO 3166-1
                            example: "250"
                        status:
                          type: string
                          description: The status of the Country Group.
                          enum:
                            - CANCELED
                            - PENDING
                            - VALIDATED
                        startDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: | 
                            The date and time at which the restriction starts. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2025-01-10 14:39:29"
                        createdDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: | 
                            The date and time at which the restriction group was created. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2025-01-10 14:39:29"
                        modifiedDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: |
                            The date and time at which the restriction group was last updated. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2025-02-12 12:45:23"
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/countryRestrictionGroups/{id}:
    get:
      tags:
        - Country Restriction Groups
      summary: Get Country Restriction Group
      description: |
        Retrieve a Country Restriction Group based on its `id`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getCountryRestrictionGroupsId
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: id
          in: path
          description: The unique identifier of the Country Group.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
        - name: fields
          in: query
          description: List of the object properties to be returned, allowing you to filter the response payload.
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  countryRestrictionGroups:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: The unique identifier of the Country Group.
                        name:
                          type: string
                          description: The name of the Country Group.
                        isWhitelist:
                          type: boolean
                          description: |
                            Indicates the kind of restriction: 
                             * `true` (default) – Allows only a specified list of countries (whitelist)
                             * `false` – Allows all countries except the specified list (blacklist)
                          default: true
                        countries:
                          type: array
                          description: The list of countries.
                          items:
                            type: string
                            description: |
                              The country in [ISO 3166-1 numeric format (a 3-digit code)](https://en.wikipedia.org/wiki/ISO_3166-1_numeric).
                            format: ISO 3166-1
                            example: "250"
                        status:
                          type: string
                          description: The status of the Country Group.
                          enum:
                            - CANCELED
                            - PENDING
                            - VALIDATED
                        startDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: | 
                            The date and time at which the restriction starts. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2024-02-15 12:45:42"
                        createdDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: | 
                            The date and time at which the restriction group was created. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2025-02-15 12:45:42"
                        modifiedDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: | 
                            The date and time at which the restriction group was last updated. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2025-02-15 12:45:42"
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    put:
      tags:
        - Country Restriction Groups
      summary: Update Country Restriction Group
      description: |
        Edit a country restriction group.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`countryGroup.update`](/guide/cards/events.html#countrygroup-update) |
      operationId: putCountryRestrictionGroups
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: id
          in: path
          description: The unique identifier of the Country Group.
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the Country Group.
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                status:
                  type: string
                  description: The status of the Country Group.
                  enum:
                    - CANCELED
                    - PENDING
                    - VALIDATED
                isWhitelist:
                  type: boolean
                  description: |
                    Indicates the kind of restriction: 
                      * `true` (default) – Allows only a specified list of countries (whitelist)
                      * `false` – Allows all countries except the specified list (blacklist)
                  default: true
                countries:
                  type: array
                  description: The list of countries.
                  items:
                    type: string
                    description: |
                      The country in [ISO 3166-1 numeric format (a 3-digit code)](https://en.wikipedia.org/wiki/ISO_3166-1_numeric).
                    format: ISO 3166-1
                    example: "250"
                startDate:
                  type: string
                  # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                  description: | 
                    The date and time at which the restriction starts. 
                    
                    Format: `YYYY-MM-DD HH:mm:ss`
                fields:
                  type: array
                  description: List of the object properties to be returned, allowing you to filter the response payload.
                  items:
                    type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  countryRestrictionGroups:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: The unique identifier of the Country Restriction Group.
                        name:
                          type: string
                          description: The name of the Country Restriction Group.
                        isWhitelist:
                          type: boolean
                          description: |
                            Indicates the kind of restriction: 
                             * `true` (default) – Allows only a specified list of countries (whitelist)
                             * `false` – Allows all countries except the specified list (blacklist)
                          default: true
                        countries:
                          type: array
                          description: The list of countries.
                          items:
                            type: string
                            description: |
                              The country in [ISO 3166-1 numeric format (a 3-digit code)](https://en.wikipedia.org/wiki/ISO_3166-1_numeric).
                            format: ISO 3166-1
                            example: "250"
                        status:
                          type: string
                          description: The status of the Country Restriction Group.
                          enum:
                            - CANCELED
                            - PENDING
                            - VALIDATED
                        startDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: | 
                            The date and time at which the restriction starts. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2021-02-15 12:45:42"
                        createdDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: | 
                            The date and time at which the restriction group was created.
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2021-02-15 12:45:42"
                        modifiedDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: |
                            The date and time at which the restriction group was created. 
                            
                            Format: `YYY-MM-DD HH:mm:ss`
                          example: "2023-02-15 12:45:42"
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
    delete:
      tags:
        - Country Restriction Groups
      summary: Cancel Country Restriction Group
      description: |
        Cancel a country restriction group.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`countryGroup.cancel`](/guide/cards/events.html#countrygroup-cancel) |
      operationId: deleteCountryRestrictionGroups
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: id
          in: path
          description: The unique identifier of the Country Group.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
        - name: fields
          in: query
          description: List of the object properties to be returned, allowing you to filter the response payload.
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  countryRestrictionGroups:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: The unique identifier of the Country Group.
                        name:
                          type: string
                          description: The name of the Country Group.
                        isWhitelist:
                          type: boolean
                          description: |
                            Indicates the kind of restriction: 
                             * `true` (default) – Allows only a specified list of countries (whitelist)
                             * `false` – Allows all countries except the specified list (blacklist)
                          default: true
                        countries:
                          type: array
                          description: The list of countries.
                          items:
                            type: string
                            description: |
                              The country in [ISO 3166-1 numeric format (a 3-digit code)](https://en.wikipedia.org/wiki/ISO_3166-1_numeric).
                            format: ISO 3166-1
                            example: "250"
                        status:
                          type: string
                          description: The status of the Country Group.
                          enum:
                            - CANCELED
                            - PENDING
                            - VALIDATED
                        startDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: | 
                            The date and time at which the restriction starts. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2021-02-15 12:45:42"
                        createdDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: | 
                            The date and time at which the restriction group was created. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2021-02-15 12:45:42"
                        modifiedDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: | 
                            The date and time at which the restriction group was last updated. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2023-02-15 12:45:42"
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/documents:
    get:
      tags:
        - User Documents
      summary: Search Documents
      description: |
        Retrieve Documents based on search criteria.

        |     |     |
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getDocuments
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: documentId
          in: query
          description: The unique identifier of the Document.
          schema:
            type: integer
            format: int64
            example: 12345
        - name: documentTag
          in: query
          description: |
            Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
            
            Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
          schema:
            type: string
            maxLength: 250
        - name: documentStatus
          in: query
          description: |
            The status of the document. See [Status](/guide/user-verification/documents.html#status-documentstatus) for more information.
          schema:
            type: string
            enum:
              - CANCELED
              - PENDING
              - VALIDATED
        - name: documentTypeId
          in: query
          description: |
            The id of the type of Document. 
            
            See [Document types](/guide/user-verification/documents.html#types-documenttypeid) for the list of values.
          schema:
            type: integer
            format: int32
            example: 9
        - name: documentType
          in: query
          description: |
            The type of the Document.

            See [Document types](/guide/user-verification/documents.html#types-documenttypeid) for the list of values.
          schema:
            type: string
            example: "ID"
        - name: userId
          in: query
          description: The unique identifier of the user the Document belongs to.
          schema:
            type: integer
            format: int64
            example: 12345
        - name: userName
          in: query
          description: The name of the user the Document belongs to.
          schema:
            type: string
            maxLength: 100
            deprecated: true
        - name: userEmail
          in: query
          description: The email of the user the Document belongs to.
          schema:
            type: string
            maxLength: 255
            # pattern: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
            example: "a.oak@example.com"
        - name: fileName
          in: query
          description: The name of the Document.
          schema:
            type: string
            maxLength: 255
            # pattern: '^[a-zA-Z0-9._-]+\.(jpg|jpeg|png|pdf|tif|svg)$'
            example: "1144214.jpg"
        - name: fileSize
          in: query
          description: The size of the Document.
          schema:
            type: integer
            format: int64
            minimum: 1
            maximum: 52428800
            deprecated: true
        - name: fileType
          in: query
          description: The file type of the Document.
          schema:
            type: integer
            format: int32
            deprecated: true
        - name: isAgent
          in: query
          description: Returns documents with no userId
          schema:
            type: boolean
            default: false
            deprecated: true
        - name: pageNumber
          in: query
          description: |
            The page number, only available on /v1/ endpoints 
          schema:
            type: integer
            format: int32
            minimum: 1
        - name: pageCount
          in: query
          description: |
            The number of items per page, only available on /v1/ endpoints  
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 20
        - name: sortBy
          in: query
          description: |
            The transaction element you want to sort the list with.
          schema:
            type: string
            default: "createdDate"
        - name: sortOrder
          in: query
          description: |
            The order you want to sort the list.
          schema:
            type: string
            default: DESC
            enum:
              - ASC
              - DESC
        - name: createdDateFrom
          in: query
          description: |
            The creation date from which you want to filter the request result.
            
            Format: `YYYY-MM-DD HH:mm:ss`. 
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2025-01-01 12:34:56"
        - name: createdDateTo
          in: query
          description: |
            The creation date up to which you want to filter the request result.
            
            Format: `YYYY-MM-DD HH:mm:ss`. 
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2025-01-02 12:34:56"
        - name: updatedDateFrom
          in: query
          description: |
            The modification date from which you want to filter the request result. 
            
            Format: `YYYY-MM-DD HH:mm:ss`. 
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2025-01-02 12:34:56"
        - name: updatedDateTo
          in: query
          description: |
            The modification date up to which you want to filter the request result.
            
            Format: `YYYY-MM-DD HH:mm:ss`. 
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2025-01-02 12:34:56"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    post:
      tags:
        - User Documents
      summary: Create Document
      description: |
        Create a Document.

        |     |     |
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`document.create`](/guide/user-verification/events.html#document-create) |
      operationId: createDocuments
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - userId
                - documentTypeId
                - name
                - fileContentBase64
              type: object
              properties:
                documentTag:
                  type: string
                  maxLength: 250
                  description: |
                    Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
                    
                    Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                userId:
                  type: integer
                  format: int64
                  minimum: 1
                  description: The unique identifier of the User the document belongs to.
                  example: 12345
                residenceId:
                  type: integer
                  format: int64
                  minimum: 1
                  description: |
                    The unique identifier of the User's [Tax Residence](/guide/users/tax-residence.html). 
                    
                    Required if the document `documentTypeId` is `24` or `25`. Shouldn't be provided otherwise.
                documentTypeId:
                  type: integer
                  format: int32
                  description: | 
                    The id of the type of Document. 
                    
                    See [Document types](/guide/user-verification/documents.html#types-documenttypeid) for the list of values.
                  example: 9
                name: 
                  type: string
                  description: The name of the document.
                  minLength: 1
                  maxLength: 255
                  # pattern: '^[a-zA-Z0-9._-]+\.(jpg|jpeg|png|pdf|tif|svg)$'
                  example: "aoak_identity_card.pdf"
                fileContentBase64:
                  type: string
                  format: byte
                  minLength: 1
                  maxLength: 70000000
                  # pattern: '^[A-Za-z0-9+/]*={0,2}$'
                  description: The file encoded in standard base64 (RFC 4648).
                  example: "U29tZSBzYW1wbGUgdGV4dA=="
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentObject'
        '303':
          description: See Other – Document already uploaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/documents/uploadUrl:
    post:
      tags:
        - User Documents
      summary: Upload Large Document
      description: |
        Get a presigned URL to upload large KYC documents.

        |     |     |
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: postUploadUrl
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - userId
                - documentTypeId
                - name
                - fileExtension
                - fileSize
                - fileHash
              type: object
              properties:
                userId:
                  type: integer
                  format: int64
                  description: The unique identifier of the User the document belongs to.
                documentTypeId:
                  type: integer
                  format: int32
                  example: 9
                  description: | 
                    The id of the type of Document. 
                    
                    See [Document types](/guide/user-verification/documents.html#types-documenttypeid) for the list of values.
                documentTag:
                  type: string
                  maxLength: 250
                  description: |
                    Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
                    
                    Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                  # pattern: '^[a-zA-Z0-9._-]+\.(jpg|jpeg|png|pdf|tif|svg)$'
                  description: The name of the document.
                  example: "aoak_identity_card.pdf"
                residenceId:
                  type: integer
                  format: int64
                  description: |
                    The unique identifier of the User's Tax Residence. Only required if the `documentTypeId` is `24` or `25`.
                fileExtension:
                  type: string
                  enum: ["jpg","png","svg","tif","pdf"]
                  description: The file extension of the document.
                  example: "pdf"
                fileSize:
                  type: integer
                  format: int64
                  minimum: 1
                  maximum: 52428800
                  description: The file size of the document. (Max 50MB)
                  example: 1048576
                fileHash:
                  type: string
                  minLength: 64
                  maxLength: 64
                  # pattern: '^[a-f0-9]{64}$'
                  description: The file hash of the document (SHA256).
                  example: "c27d4142972f30ac6ead183e54437f1b993a64994b342a7261337bc5a7a7e447"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  documentId:
                    type: integer
                    format: int64
                    description: The unique identifier of the document.
                  uploadUrl:
                    type: string
                    format: uri
                    maxLength: 2048
                    # pattern: '^https://.+'
                    description: The presigned URL for uploading the document
                    example: "https://treezor-env-kyc-documents.s3.eu-central-1.amazonaws.com"
                  values:
                    type: object
                    description: Necessary information for your upload request.
                    properties:
                      Content-Type:
                        type: string
                        enum: ["image/jpg", "image/png", "image/svg+xml", "image/tiff", "application/pdf"]
                        description: The MIME type of the content to be uploaded.
                        example: "image/jpg"
                      X-Amz-Algorithm:
                        type: string
                        enum: ["AWS4-HMAC-SHA256"]
                        description: The AWS signature version 4 algorithm used for authentication.
                        example: "AWS4-HMAC-SHA256"
                      X-Amz-Credential:
                        type: string
                        # pattern: '^[A-Z0-9]+/\d{8}/[a-z-]+/s3/aws4_request$'
                        description: The access key ID, date, region, service, and request type for AWS authentication.
                        example: "ASIAWTKIE63PHMITE2UI/20250627/eu-central-1/s3/aws4_request"
                      X-Amz-Date:
                        type: string
                        format: ISO 8601
                        # pattern: '^\d{8}T\d{6}Z$'
                        description: The date and time the request was signed, in ISO-8601 format (YYYYMMDDTHHMMSSZ).
                        example: "20250627T085858Z"
                      X-Amz-Meta-autovalidate:
                        type: string
                        enum: ["true", "false"]
                        description: Indicates whether the document should be automatically validated after upload.
                        example: "true"
                      X-Amz-Meta-client:
                        type: string
                        # pattern: '^\d+$'
                        description: The client identifier associated with the document upload.
                        example: "929252"
                      X-Amz-Meta-full_filename:
                        type: string
                        maxLength: 255
                        # pattern: '^[a-zA-Z0-9._-]+\.(jpg|jpeg|png|pdf|tif|svg)$'
                        description: The full original filename of the document being uploaded.
                        example: "1236303.jpg"
                      X-Amz-Security-Token:
                        type: string
                        minLength: 100
                        description: The security token for temporary AWS credentials.
                        example: "IQoJb3JpZ2luX2VjEHkaDGV1LWNlbnRyYWwtMSJHMEUCIHrMj/uSzVFwjad7FC0q1NzFEkG8Z0TSoFmM0sqw18djAiEAmQpl2HjYUVbIdzH60WxQLp63k6lp5kfIUmXmo+004qwqogMIchABGgw0NTM4MDcyNDA5MjYiDOUY8utA+ZeKZPfg5Sr/Av+3a0jDCHeGupXwF8OrXGb2tPXWDNXKpm/AO7Zx0rlWoglaQVgvvbX4+We+7K1mS/KOIexQh+YtKUkNthOIZLaG75PtzcGS+yDdMbwE4tv/+oMH1k//oBL9vSmUsVEiBQqpc0UvcbAIfieavY8EBjvSKOZ0uh01QmyEh6Q4O5p3wb50l2YbFV4aQct4PvZvEHVwo2Xj7r8axmYk4bKOlJE/c2xBQJ2ZbbrNd3g11Y50Bbs7XSHLEVnFPZsQKmeNsJ7pOA6kLSxItbhVoI1/lmZGVxx/DkqHLedXBnatOPb+CSpCmCmtOnLNGeBKWASOIuqJu0RMT+AWcP0aHtQ4Zuy0grqgO8eG20nZ9B2w4eTa2Xr/burwbvyzd6Fpt0SG493xs1/+3aSQFpvL6wCbRnqkXA+YXQeoLDyzbajIW7uWLJ5b5Mj6XYSQ5lQVWJ2XTGypPXlYM2BpCJyvLgfFzBqqeKYqBVXUbEONFsJba15vFX7MPzrENxzzg3zxWFPdMJ2z+cIGOp0B4ga4EkvvoeH0GD1IfWLiv3CKjcEcsZjen6G64kgWBuo9lzCkwQvKNQf20NGCrAEwLQ8iFd+wzFnxiM5Z9pKcYLseIfiZJhw+DlxOAIkAS1Pnbbk7J1WjZEkzZE3fJQNgYng2xrOy7yMTccogNnIylTXd6nqJzpwBQrSF8uTZuwufo9fvg9uKPjZJnWUd9Njt5YTX0qO9SjSP64LE8w=="
                      X-Amz-Signature:
                        type: string
                        # pattern: '^[a-f0-9]{64}$'
                        description: The computed signature for the AWS request.
                        example: "5493f0de76c0897f0ca16fc914f55cf811cc359dcf0fb8bc7caa9e5cb03817fd"
                      X-Amz-checksum-algorithm:
                        type: string
                        enum: ["SHA256"]
                        description: The checksum algorithm used for the uploaded file.
                        example: "SHA256"
                      X-Amz-checksum-sha256:
                        type: string
                        format: byte
                        # pattern: '^[A-Za-z0-9+/]*={0,2}$'
                        description: The SHA256 checksum of the file content, Base64 encoded.
                        example: "cGBpcc6jOCh2KXJDpvgHiPakOd8UTPT+bcmueZN7PtM="
                      key:
                        type: string
                        maxLength: 1024
                        # pattern: '^client_\d+/user_\d+/[a-zA-Z0-9._-]+$'
                        description: The key (path and filename) for the object in the S3 bucket.
                        example: "client_929252/user_102273999/1236303.jpg"
                      policy:
                        type: string
                        format: byte
                        description: The Base64 encoded AWS policy document that specifies the conditions for the upload.
                        example: "eyJjb25kaXRpb25zIjpbXX0="
                  expireIn:
                    type: number
                    format: double
                    minimum: 60
                    maximum: 3600
                    example: 120
                    description: The expiration of the URL in seconds.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write

  /v1/documents/{documentId}:
    get:
      tags:
        - User Documents
      summary: Get Document
      description: |
        Retrieve a Document using its `id`.

        |     |     |
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getDocument
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: documentId
          in: path
          description: The unique identifier of the Document.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    put:
      tags:
        - User Documents
      summary: Update Document
      description: |
        Change the `name` of a Document.

        |     |     |
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`document.update`](/guide/user-verification/events.html#document-update) |
      operationId: putDocument
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: documentId
          in: path
          description: The unique identifier of the Document.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                  # pattern: '^[a-zA-Z0-9._-]+\.(jpg|jpeg|png|pdf|tif|svg)$'
                  description: The name of the document.
                  example: "updated_document_name.pdf"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
    delete:
      tags:
        - User Documents
      summary: Delete Document
      description: |
        Remove a document.

        |     |     |
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`document.delete`](/guide/user-verification/events.html#document-delete) |
      operationId: deleteDocument
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: documentId
          in: path
          description: The unique identifier of the Document.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/documents/{documentId}/download:
    get:
      tags:
        - User Documents
      summary: Get Document Download URL
      description: |
        Retrieve a Document download URL. See [Download documents](/guide/user-verification/documents.html#download-documents) for more information.

        |     |     |
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getDocumentDownloadUrl
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: documentId
          in: path
          description: The unique identifier of the Document.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    format: uri
                    maxLength: 2048
                    # pattern: '^https://.+'
                    description: The URL to download the Document
                    example: "https://example.com/document.pdf"
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
  /v1/issuerInitiatedDigitizationDatas:
    post:
      tags:
        - Digitized Cards
      summary: Request issuerInitiatedDigitizationData
      description: | 
        Create a new issuerInitiatedDigitizationData request.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-operation |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: tavRequestPOST
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - cardId
                - tokenRequestor
              type: object
              properties:
                cardId:
                  type: integer
                  description: |
                    The unique identifier of the card.
                  example: 12345
                tokenRequestor:
                  type: string
                  description: The name of the wallet provider.
                  enum: [APPLE,GOOGLE]
                googleServerSessionId:
                  type: string
                  description: |
                    The Google server session ID, required when `tokenRequestor` is `GOOGLE` and using the Google OPC flow.
                    
                    This ID is provided by the Google Pay SDK and is used to generate the encrypted OPC payload.
                  example: "GoogleSession123"
                additionnalData:
                  type: object
                  description: |
                    This object is required when the `tokenRequestor` is `APPLE`.
                  properties:
                    certificates:
                      type: array
                      description: |
                        The certificate chain. Required when the `tokenRequestor` is `APPLE`.
                        
                        The first element of array is the leaf certificate and the last should be the root certificate.
                        There can be 0 or several sub certificates inbetween the first element of array and the last. 
                        All certificates are of type string (base64 encoded of DER format).
                      items:
                        type: string
                        format: byte
                        example: "U29tZSBzYW1wbGUgdGV4dA=="
                    nonce:
                      type: string
                      format: byte
                      description: |
                        The nonce as provided by the Apple SDK. Required when `tokenRequestor` is `APPLE`.
                    nonceSignature:
                      type: string
                      format: byte
                      description: |
                        The nonce signature as provided by the Apple SDK. Required when `tokenRequestor` is `APPLE`.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  issuerInitiatedDigitizationDatas:
                    type: array
                    items:
                      type: object
                      properties:
                        additionnalData:
                          type: array
                          description: |
                            Please note Treezor doesn't persist this information for security reasons.
                          items:
                            type: string
                        cardId:
                          type: integer
                          description: The unique identifier of the card.
                          example: 12345
                        createdDate:
                          type: string
                          description: |
                            The date and time at which the credential was created.

                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2025-02-19 14:30:45"
                        credential:
                          type: string
                          description: The credentials to use for digitization request.
                        id:
                          type: integer
                          description: The unique identifier of the request.
                          example: 876543
                        modifiedDate:
                          type: string
                          description: |
                            The date and time at which the credential was created.

                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2025-02-19 14:30:45"
                        statusId:
                          type: integer
                          description: |
                            The status ID of the TAV request. Can be: 
                            * `1` – issuerInitiatedDigitizationData has been requested"
                            * `2` – data object can be retrieved.
                          enum: [ 1,2 ]
                        tokenRequestor:
                          type: string
                          description: The name of the wallet provider.
                          enum: [APPLE,GOOGLE]
                          example: "APPLE"
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/mandates:
    get:
      tags:
        - Mandates
      summary: Search Mandates
      description: |
        Retrieve Mandates that match search criteria.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getMandates
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: mandateId
          in: query
          description: The unique identifier of the Mandate.
          schema:
            type: integer
            example: 12345
        - name: userId
          in: query
          description: The unique identifier of the User who initiates the Mandate request.
          schema:
            type: integer
            example: 12345
        - name: uniqueMandateReference
          in: query
          description: |
            The unique reference that unambiguiously identify a mandate signed between the user and the beneficiary. 
                          
            See the [Unique Mandate Reference (UMR)](/guide/overview/glossary.html#unique-mandate-reference-umr) article for more information.
          schema:
            type: string
        - name: mandateStatus
          in: query
          description: |
            The status of the Mandate.
          schema:
            type: string
            enum: [CANCELED, PENDING, VALIDATED]
        - name: filter
          in: query
          description: |
            You can filter the API response by using filter(s).

            Filters should be separated by a ";". Example for 3 filters: `FILTER1;FILTER2;FILTER3`

            A single filter has the following syntax : "fieldName criterionexpression".

            Where:
            * fieldName – the name of a filterable field of this object.
            * expression – the values to be included or excluded (see the table below for more information)
            * criterion – a filter criterion.

            Here are the possible values for criterion:

             | Criteria |         Description    |                   Type                   | Expression Example |
             |----------|------------------------|------------------------------------------|--------------------|
             |     >    |      greater than      |            alphanumeric string           |         100        |
             |    >=    | greater or equal than  |            alphanumeric string           |         100        |
             |     <    |        less than       |            alphanumeric string           |         100        |
             |    <=    |   less or equal than   |            alphanumeric string           |         100        |
             |    !=    |      not equal to      |            alphanumeric string           |         100        |
             |   like   |          like          |            alphanumeric string           |         100        |
             |    in    |           in           | alphanumeric strings separated by commas |      100,30,25     |
             |    ==    |         equals         |            alphanumeric string           |         100        |
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MandateObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    post:
      tags:
        - Mandates
      summary: Create Mandate
      description: |
        Create a new mandate.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`mandate.create`](/guide/transfers/events.html#mandate-create) |
      operationId: postMandates
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - sddType
                - isPaper
                - userId
                - debtorName
                - debtorAddress
                - debtorCity
                - debtorZipCode
                - debtorCountry
                - debtorIban
                - debtorBic
                - sequenceType
                - signatureDate
              type: object
              properties:
                sddType:
                  type: string
                  description: |
                    The type of Mandate, which can be:
                    * `core` – To debit individuals (physical persons).
                    * `b2b` – To debit legal entities.
                  enum: ["core", "b2b"]
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                isPaper:
                  type: boolean
                  description: | 
                    Whether the Mandate is a paper-based document, or electronically signed. As of today, should only be set to `true`.
                userId:
                  type: integer
                  description: The unique identifier of the end user requesting the SEPA Direct Debit (i.e., the creditor initiating the Mandate request).
                debtorName:
                  type: string
                  format: alphanumeric
                  description: |
                    The full name of the debited entity or individual. Format: alphanumeric with at least 3 alphabetic characters.
                debtorAddress:
                  type: string
                  description: The address of the debited end user. 
                debtorCity:
                  type: string
                  description: The city in which the debited end user is domiciled.
                debtorZipCode:
                  type: string
                  description: The postcode of the city in which the debited end user is domiciled.
                debtorCountry:
                  type: string
                  description: Country in which the debited end user is domiciled.
                  format: ISO 3166-1 alpha-2
                  example: "FR"
                debtorIban:
                  type: string
                  description: IBAN of the debited user.
                  example: "FR763000100794123XXXXXXXX"
                debtorBic:
                  type: string
                  description: The BIC (or SWIFT) of the debited user
                  example: "BDFXXXXXX"
                sequenceType:
                  type: string
                  description: |
                    Defines whether or not the debtor will be debited multiple times. Can be one of the following:
                    * `one-off` – For a one-time payment.
                    * `recurrent` – For recurring payments.
                  enum:
                    - one-off
                    - recurrent
                createdIp:
                  type: string
                  description: IP address of the end user requesting the SDD.
                signatureDate:
                  type: string
                  format: date
                  description: |
                    Date on which the Mandate was signed by the end user.

                    Format: `YYYY-MM-DD`
                  example: "2024-10-03"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MandateObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/mandates/{mandateId}:
    get:
      tags:
        - Mandates
      summary: Get Mandate
      description: |
        Retrieve a Mandate based on its `id`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getMandate
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: mandateId
          in: path
          description: The unique identifier of the Mandate.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MandateObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    delete:
      tags:
        - Mandates
      summary: Revoke Mandate
      description: |
        Change the Mandate status to `CANCELED`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: deleteMandate
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: mandateId
          in: path
          description: The unique identifier of the Mandate.
          required: true
          schema:
            type: integer
            example: 12345
        - name: origin
          in: query
          description: | 
            The origin of the request for revoking the Mandate.
          required: true
          schema:
            type: string
            enum:
              - CREDITOR
              - DEBITOR
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MandateObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/mccRestrictionGroups:
    get:
      tags:
        - MCC Restriction Groups
      summary: Search MCC Restriction Groups
      description: | 
        Retrieve MCC Restriction Groups that match search criteria.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** |  |
      operationId: getMccRestrictionGroups
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: fields
          in: query
          description: List of the object properties to be returned, allowing you to filter the response payload.
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: filter
          in: query
          description: |
            You can filter the API response by using filter(s).
            Filterable fields are:
              - id
              - name
              - isWhitelist
              - status
              - startDate
              - createdDate

            Filters should be separated by a ";". Example for 3 filters: FILTER1;FILTER2;FILTER3.

            A single filter has the following syntax: "fieldName criterion expression", where:
            * fieldName: the name of a filterable field of this object.
            * expression: the values to be included or excluded (see table below)
            * criterion: a filter criterion.

            Here are the possible values for criterion:

              | Criteria |         Description    |                   Type                   | Expression Example |
              |----------|------------------------|------------------------------------------|--------------------|
              |     >    |      greater than      |            alphanumeric string           |         100        |
              |    >=    | greater or equal than  |            alphanumeric string           |         100        |
              |     <    |        less than       |            alphanumeric string           |         100        |
              |    <=    |   less or equal than   |            alphanumeric string           |         100        |
              |    !=    |      not equal to      |            alphanumeric string           |         100        |
              |   like   |          like          |            alphanumeric string           |         100        |
              |    in    |           in           | alphanumeric strings separated by commas |      100,30,25     |
              |    ==    |         equals         |            alphanumeric string           |         100        |
          schema:
            type: string
        - name: pageNumber
          in: query
          description: |
            The page number, only available on /v1/ endpoints 
          schema:
            type: integer
        - name: pageCount
          in: query
          description: |
            The number of items per page, only available on /v1/ endpoints  
          schema:
            type: integer
        - name: sortBy
          in: query
          description: |
            The transaction element you want to sort the list with.
          schema:
            type: string
            default: "createdDate"
        - name: sortOrder
          in: query
          description: |
            The order you want to sort the list.
          schema:
            type: string
            default: DESC
            enum:
              - DESC
              - ASC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  mccRestrictionGroups:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: The unique identifier of the MCC Group.
                        name:
                          type: string
                          description: The name of the MCC Group.
                        isWhitelist:
                          type: boolean
                          description: |
                            Indicates the kind of restriction: 
                            * `true` (default) – Allows only a specified list of merchant caegories (whitelist)
                            * `false` – Allows all merchant categories except the specified list (blacklist)
                          default: true
                        mcc:
                          type: array
                          description: The list of MCC (each item is an integer).
                          items:
                            type: integer
                        status:
                          type: string
                          description: The status of the MCC group.
                          enum:
                            - CANCELED
                            - PENDING
                            - VALIDATED
                        startDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: |
                            The date and time at which the restriction starts. Defaults to the date and time of creation. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2020-03-05 12:34:11"
                        createdDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: |
                            The date and time at which the restriction group was created. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2020-03-05 12:34:11"
                        modifiedDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: |
                            The date and time at which the restriction group was last updated. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2021-02-08 15:41:21"
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    post:
      tags:
        - MCC Restriction Groups
      summary: Create MCC Restriction Group
      description: |
        Create a new Merchant Category Code (MCC) restriction group.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`mccGroup.create`](/guide/cards/events.html#mccgroup-create) |
      operationId: postMccRestrictionGroup
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: fields
          in: query
          description: List of the object properties to be returned, allowing you to filter the response payload.
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
      requestBody:
        content:
          application/json:
            schema:
              required:
                - mcc
                - name
              type: object
              properties:
                name:
                  type: string
                  description: The name of the MCC Group.
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                status:
                  type: string
                  description: The status of the MCC group.
                  default: "PENDING"
                  enum:  
                    - CANCELED          
                    - PENDING
                    - VALIDATED
                isWhitelist:
                  type: boolean
                  description: |
                    Indicates the kind of restriction: 
                    * `true` (default) – Allows only a specified list of merchant caegories (whitelist)
                    * `false` – Allows all merchant categories except the specified list (blacklist)
                  default: true
                mcc:
                  type: array
                  description: The list of MCC (each item is an integer).
                  items:
                    type: integer
                startDate:
                  type: string
                  # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                  description: |
                    The date and time at which the restriction starts. Defaults to the date and time of creation.
                    
                    Format: `YYYY-MM-DD HH:mm:ss`
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  mccRestrictionGroups:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: The unique identifier of the MCC restriction group.
                        name:
                          type: string
                          description: The name of the MCC restriction group.
                        isWhitelist:
                          type: boolean
                          description: |
                            Indicates the kind of restriction: 
                            * `true` (default) – Allows only a specified list of merchant caegories (whitelist)
                            * `false` – Allows all merchant categories except the specified list (blacklist)
                          default: true
                        mcc:
                          type: array
                          description: The list of MCC (each item is an integer)
                          items:
                            type: integer
                        status:
                          type: string
                          description: The status of the MCC group.
                          enum:
                            - PENDING
                            - CANCELED
                            - VALIDATED
                        startDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: |
                            The date and time at which the restriction starts. Defaults to the date and time of creation. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2025-01-22 12:23:34"
                        createdDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: |
                            The date and time at which the restriction group was created.

                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2025-01-22 12:23:34"
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/mccRestrictionGroups/{id}:
    get:
      tags:
        - MCC Restriction Groups
      summary: Get MCC Restriction Group
      description: |
        Retrieve a MCC Group based on its `id`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getMccRestrictionGroupsId
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: id
          in: path
          description: The unique identifier of the MCC Restriction Group.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
        - name: fields
          in: query
          description: List of the object properties to be returned, allowing you to filter the response payload.
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  mccRestrictionGroups:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: The unique identifier of the MCC Restriction Group.
                        name:
                          type: string
                          description: The name of the MCC Restriction Group.
                        isWhitelist:
                          type: boolean
                          description: |
                            Indicates the kind of restriction: 
                            * `true` (default) – Allows only a specified list of merchant caegories (whitelist)
                            * `false` – Allows all merchant categories except the specified list (blacklist)
                          default: true
                        mcc:
                          type: array
                          description: List of MCC (each item is an integer)
                          items:
                            type: integer
                        status:
                          type: string
                          description: The status of the MCC group.
                          enum:
                            - PENDING
                            - CANCELED
                            - VALIDATED
                        startDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: |
                            The date and time at which the restriction starts. Defaults to the date and time of creation. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2023-03-05 12:34:11"
                        createdDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: | 
                            The date and time at which the restriction group was created. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2023-03-05 12:34:11"
                        modifiedDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: | 
                            The date and time at which the restriction group was last updated. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2025-03-05 12:34:11"
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    put:
      tags:
        - MCC Restriction Groups
      summary: Update MCC Restriction Group
      description: |
        Edit a MCC Restriction group.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`mccGroup.update`](/guide/cards/events.html#mccgroup-update) |
      operationId: putMccRestrictionGroups
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: id
          in: path
          description: The unique identifier of the MCC Restriction Group.
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the MCC restriction group
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                status:
                  type: string
                  description: Status of the MCC restriction group
                  enum:
                    - VALIDATED
                    - PENDING
                    - CANCELED
                isWhitelist:
                  type: boolean
                  description: determines whether it will be a black or a white list
                  default: true
                mcc:
                  type: array
                  description: Array of MCC
                  items:
                    type: integer
                startDate:
                  type: string
                  # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                  description: |
                    The date at which the MCC restriction group will be take into account.
                    
                    Format: `YYYY-MM-DD HH:mm:ss`
                  example: "2024-10-23 12:19:49"
                fields:
                  type: array
                  description: List of the object properties to be returned, allowing you to filter the response payload.
                  items:
                    type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  mccRestrictionGroups:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: The unique identifier of the MCC restriction group
                        name:
                          type: string
                          description: The name of the MCC restriction group
                        isWhitelist:
                          type: boolean
                          description: |
                            Indicates the kind of restriction: 
                            * `true` (default) – Allows only a specified list of merchant caegories (whitelist)
                            * `false` – Allows all merchant categories except the specified list (blacklist)
                          default: true
                        mcc:
                          type: array
                          description: The list of MCC (each item is an integer)
                          items:
                            type: integer
                        status:
                          type: string
                          description: The status of the MCC restriction group
                          enum:
                            - PENDING
                            - CANCELED
                            - VALIDATED
                        startDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: | 
                            The date and time at which the restriction starts. Defaults to the date and time of creation. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2025-03-05 12:34:11"
                        createdDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: | 
                            The date and time at which the restriction group was created. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2025-03-05 12:34:11"
                        modifiedDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: | 
                            The date and time at which the restriction group was last updated. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2025-05-05 12:34:11"

        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
    delete:
      tags:
        - MCC Restriction Groups
      summary: Cancel MCC Restriction Group
      description: |
        Cancel a MCC restriction group.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`mccGroup.cancel`](/guide/cards/events.html#mccgroup-cancel) |
      operationId: deleteMccRestrictionGroups
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: id
          in: path
          description: The unique identifier of the MCC restriction Group.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
        - name: fields
          in: query
          description: List of the object properties to be returned, allowing you to filter the response payload.
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  mccRestrictionGroups:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: The unique identifier of the MCC restriction group.
                        name:
                          type: string
                          description: The name of the MCC restriction group.
                        isWhitelist:
                          type: boolean
                          description: |
                            Indicates the kind of restriction: 
                            * `true` (default) – Allows only a specified list of merchant caegories (whitelist)
                            * `false` – Allows all merchant categories except the specified list (blacklist)
                          default: true
                        mcc:
                          type: array
                          description: The list of MCC (each item is an integer).
                          items:
                            type: integer
                        status:
                          type: string
                          description: The status of the MCC restriction group.
                          enum:
                            - PENDING
                            - CANCELED
                            - VALIDATED
                        startDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: | 
                            The date and time at which the restriction starts. Defaults to the date and time of creation. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2025-03-05 12:34:11"
                        createdDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: | 
                            The date and time at which the restriction group was created. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2025-03-05 12:34:11"
                        modifiedDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: | 
                            The date and time at which the restriction group was last updated. 
                            
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2025-05-05 12:34:11"
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/merchantIdRestrictionGroups:
    get:
      tags:
        - Merchant ID Restriction Groups
      summary: Search MID Restriction Groups
      description: |
        Retrieve Merchant ID Restriction Groups that match search criteria.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getMerchantIdRestrictionGroup
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: fields
          in: query
          description: List of the object properties to be returned, allowing you to filter the response payload.
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: filter
          in: query
          description: |
            You can filter the API response by using filter(s).
            Filterable fields are:
              - id
              - name
              - isWhitelist
              - status
              - startDate
              - createdDate

            Filters should be separated by a ";". Example for 3 filters: FILTER1;FILTER2;FILTER3.

            A single filter has the following syntax: "fieldName criterion expression", where:
            - fieldName: the name of a filterable field of this object.
            - expression: the values to be included or excluded (see the table below for more information)
            - criterion: a filter criterion.

            Here are the possible values for criterion:

              | Criteria |         Description    |                   Type                   | Expression Example |
              |----------|------------------------|------------------------------------------|--------------------|
              |     >    |      greater than      |            alphanumeric string           |         100        |
              |    >=    | greater or equal than  |            alphanumeric string           |         100        |
              |     <    |        less than       |            alphanumeric string           |         100        |
              |    <=    |   less or equal than   |            alphanumeric string           |         100        |
              |    !=    |      not equal to      |            alphanumeric string           |         100        |
              |   like   |          like          |            alphanumeric string           |         100        |
              |    in    |           in           | alphanumeric strings separated by commas |      100,30,25     |
              |    ==    |         equals         |            alphanumeric string           |         100        |
          schema:
            type: string
        - name: pageNumber
          in: query
          description: |
            The page number, only available on /v1/ endpoints 
          schema:
            type: integer
        - name: pageCount
          in: query
          description: |
            The number of items per page, only available on /v1/ endpoints  
          schema:
            type: integer
        - name: sortBy
          in: query
          description: |
            The transaction element you want to sort the list with.
          schema:
            type: string
            default: "creationDate"
        - name: sortOrder
          in: query
          description: |
            The order you want to sort the list.
          schema:
            type: string
            default: DESC
            enum:
              - DESC
              - ASC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantIdGroupObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    post:
      tags:
        - Merchant ID Restriction Groups
      summary: Create MID Restriction Group
      description: |
        Create a new Merchant ID restriction group.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`merchantIdGroup.create`](/guide/cards/events.html#merchantidgroup-create) |
      operationId: postMerchantIdRestrictionGroup
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - merchants
                - name
              type: object
              properties:
                name:
                  type: string
                  description: Name of the Merchant ID restriction group.
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                status:
                  type: string
                  description: The status of the Merchant ID restriction group.
                  default: "PENDING"
                  enum:
                    - VALIDATED
                    - PENDING
                    - CANCELED
                isWhitelist:
                  type: boolean
                  description: |
                      Indicates the kind of restriction: 
                      * `true` (default) – Allows only a specified list of merchant ids (whitelist)
                      * `false` – Allows all merchant ids except the specified list (blacklist)
                  default: true
                merchants:
                  type: array
                  description: List of Merchant Ids (each item is a string).
                  items:
                    type: string
                startDate:
                  type: string
                  # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                  description: |
                    The date and time at which the restriction starts. 
                    
                    Format: `YYYY-MM-DD HH:mm:ss`
                  example: "2023-10-23 12:19:49"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantIdGroupObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/merchantIdRestrictionGroups/{id}:
    put:
      tags:
        - Merchant ID Restriction Groups
      summary: (DEPRECATED) Update MID Restriction Group
      description: Deprecated
      operationId: putMerchantIdRestrictionGroups
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: id
          in: path
          description: The unique identifier of the Merchant Id restriction group.
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the merchant ID restriction group
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                status:
                  type: string
                  description: Status of the merchant ID restriction group
                  enum:
                    - CANCELED
                    - PENDING
                    - VALIDATED
                isWhitelist:
                  type: boolean
                  description: |
                    Indicates the kind of restriction: 
                    * `true` (default) – Allows only a specified list of merchant ids (whitelist)
                    * `false` – Allows all merchant ids except the specified list (blacklist)
                  default: true
                merchants:
                  deprecated: true
                  type: array
                  description: |
                    (Deprecated. Use `PUT /merchantIdRestrictionGroups/{id}/DeltaUpdate` to update merchants ID list)
                  items:
                    type: string
                startDate:
                  type: string
                  # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                  description: |
                    The date and time at which the restriction starts. 
                    
                    Format: `YYYY-MM-DD HH:mm:ss`
                  example: "2024-10-23 12:19:49"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantIdGroupObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
    delete:
      tags:
        - Merchant ID Restriction Groups
      summary: Cancel MID Restriction Group
      description: |
        Cancel a merchant id restriction group.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`merchantIdGroup.cancel`](/guide/cards/events.html#merchantidgroup-cancel) |
      operationId: deleteMerchantIdRestrictionGroups
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: id
          in: path
          description: The unique identifier of the Merchant ID restriction group.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
        - name: fields
          in: query
          description: List of the object properties to be returned, allowing you to filter the response payload.
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantIdGroupObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/merchantIdRestrictionGroups/{id}/DeltaUpdate:
    put:
      tags:
        - Merchant ID Restriction Groups
      summary: Update MID Restriction Group
      operationId: put-merchandidrestrictiongroups-deltaupdate
      description: |
        Update the list of Merchant Ids for a MID Restriction Group.


        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`merchantIdGroup.update`](/guide/cards/events.html#merchantidgroup-update) |
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: id
          in: path
          description: The unique identifier of the Merchant ID restriction group.
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                merchants:
                  type: array
                  description: The list of Merchant Ids (each item is a string)
                  items:
                    type: string
                merchantsOperation:
                  type: string
                  description: Whether to `add` or `removed` the Merchant Ids.
                  enum:
                    - add
                    - remove
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantIdGroupObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/merchantIdRestrictionGroups/{id}/PresenceCheck:
    put:
      tags:
        - Merchant ID Restriction Groups
      summary: Check the presence of merchants IDs list for a restriction group
      operationId: put-midrestrictiongroups
      description: Check if Merchant IDs list for a restriction group.
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: id
          in: path
          description: The unique identifier of the Merchant ID restriction group.
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                merchants:
                  type: array
                  description: The list of Merchant Ids (each item is a string).
                  items:
                    type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantIdGroupObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
  /v1/payins:
    get:
      tags:
        - Payins
      summary: Search Payins
      description: |
        Retrieve payins that match search criteria. The request must contain at least one of the following inputs: `payinId`, `walletId`, or `payinTag`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getPayins
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: payinId
          in: query
          description: |
            The unique identifier of the payin. Required if `walletId` or `payinTag` are not provided.
          schema:
            type: integer
            example: 12345
        - name: walletId
          in: query
          description: The unique identifier of the Wallet of the payin.  Required if `payinId` or `payinTag` are not provided.
          schema:
            type: integer
            example: 12345
        - name: payinTag
          in: query
          description: |
            Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.

            Required if `payinId` or `walletId` are not provided. 
            
            Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
          schema:
            type: string
            maxLength: 250
            example: "INVOICE-2025-04-001"
        - name: cursor
          in: query
          description: Pagination cursor, if you don't pass a cursor, result will start at the first page.
          schema:
            type: string
            example: "da4b9237bacccdf19c0760cab7aec4a8359010b0"
        - name: pageSize
          in: query
          description: |
            The number of items to return per page.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
            example: 20
        - name: sortOrder
          in: query
          description: |
            The order in which you want to sort the list based on the payin's date.
            * **DESC** for descending.
            * **ASC** for ascending.
          schema:
            type: string
            enum:
              - ASC
              - DESC
            default: DESC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayinObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    post:
      tags:
        - Payins
      summary: Create Payin
      description: | 
        Create a new payin.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A|
        | **[Webhook](/guide/webhooks/introduction.html)** | `payin.create` |
      operationId: postPayin
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
              - walletId
              - userId
              - paymentMethodId
              - amount
              - currency
              type: object
              properties:
                payinTag:
                  type: string
                  maxLength: 250
                  description: | 
                    Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
                    
                    Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
                walletId:
                  type: string
                  description: |
                    The unique identifier of the credited Wallet.
                  example: "878744"
                userId:
                  type: string
                  description: |
                    The unique identifier of the User making the payin.

                    Note that for the `paymentMethodId` of `21` and `26`, you don't need to provide this value.
                    It will be set automatically by Treezor.
                  example: "1656177"
                paymentMethodId:
                  type: string
                  description: |
                    The type of payin.

                    | Id | Payment by |
                    | ---| --- |
                    | `20` | [Received SEPA Credit Transfer (SCTR)](/guide/transfers/credit-transfer.html#received-credit-transfers-sctr). You can only create such payins in Sandbox, otherwise created automatically upon receiving a transfer. |
                    | `21` | [Emitted SEPA Core Direct Debit (SDDE Core)](/guide/transfers/direct-debit.html#emitted-direct-debits-sdde). |
                    | `22` | [Emitted SEPA B2B Direct Debit (SDDE B2B)](/guide/transfers/direct-debit.html#emitted-direct-debits-sdde). |
                    | `23` | **Deprecated** (Full Hosted HTML Payment Form). |
                    | `24` | **Deprecated** (IFrame Payment Form). |
                    | `25` | [Card topups](/guide/acquiring/introduction.html). You cannot create a payin directly with this method id. The payin will be automatically created by Treezor. |
                    | `26` | [Check cashing](/guide/cheques/introduction.html) |
                    | `27` | [Received SEPA Instant Credit Transfer](/guide/transfers/credit-transfer-inst.html#received-instant-credit-transfers-sctr-inst). You cannot create a payin directly with this method id. The payin will be automatically created by Treezor. |
                    | `28` | [Received International Transfer](/guide/transfers/international.html#received-international-transfers). You cannot create a payin directly with this method id. The payin will be automatically created by Treezor. |
                  enum: ["20", "21", "22", "23", "24", "25", "26", "27", "28"]
                amount:
                  type: string
                  description: |
                    The amount of the payin.
                  example: "12.34"
                currency:
                  type: string
                  format: ISO 4217
                  description: |
                    The currency of the payin in [ISO 4217](/guide/api-basics/data-format.html#currencies) format. Must be the same as the Wallet currency.
                  example: "EUR"
                paymentAcceptedUrl:
                  type: string
                  description: |
                    URL to which the cardholder is redirected if payment is successful.
                paymentWaitingUrl:
                  type: string
                  description: | 
                    URL to which the cardholder is redirected to wait payment processing. 
                paymentCanceledUrl:
                  type: string
                  description: |
                    URL to which the cardholder is redirected if payment is canceled.
                paymentRefusedUrl:
                  type: string
                  description: |
                    URL to which the cardholder is redirected if payment is refused.
                paymentExceptionUrl:
                  type: string
                  description: |
                    URL to which the cardholder is redirected if the payment process raised an exception.
                distributorFee:
                  type: string
                  nullable: true
                  deprecated: true
                messageToUser:
                  type: string
                  description:
                    Message to send to Wallet of the user. For SEPA Direct Debit Core payment method, this parameter reconciles information transmitted to the Debtor (i.e., Invoice number). In this case, it can't exceed 140 characters.
                  example: "Invoice ref.123456"
                language:
                  type: string
                  description: Language for the third party interface.
                  enum:
                    - FRA
                    - GBR
                    - ESP
                    - ITA
                    - PRT
                createdIp:
                  type: string
                  description: The IP address of the User.
                payinDate:
                  type: string
                  example: "2025-05-18"
                  description: |
                    The date at which the SDD should be presented. 
                    
                    In the case of SDD Core, this parameter defaults to the third working day following the payin creation if left empty. 
                    
                    Format: `YYYY-MM-DD`, a [SEPA Open Banking Day](/guide/overview/glossary.html#sepa-open-banking-days) is expected, based on the rules described in the [dedicated article](/guide/transfers/direct-debit.html#parameters).
                mandateId: 
                  type: integer
                  description: The unique identifier of the Mandate. This parameter is mandatory when performing a payin with method SDD Core.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayinObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/payins/{payinId}:
    get:
      tags:
        - Payins
      summary: Get Payin
      description: |
        Retrieve a payin by its id.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only`, `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getPayin
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: payinId
          in: path
          description: The unique identifier of the payin.
          required: true
          schema:
            type: string
            example: "12345"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayinObject'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    delete:
      tags:
        - Payins
      summary: Delete Payin
      description: | 
        Cancels a Payin. This endpoint is only available for:
        * [Check cashing](/guide/cheques/introduction.html), before the treatment center receives the check.
        * [SEPA Direct Debit emission](/guide/transfers/direct-debit.html#emitted-direct-debits-sdde), before Treezor processes it.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | `payin.cancel` |
      operationId: deletePayin
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: payinId
          in: path
          description: The unique identifier of the payin.
          required: true
          schema:
            type: string
            example: "12345"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayinObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/payinrefunds:
    get:
      tags:
        - Payin Refunds
      summary: Search Payin Refunds
      description: | 
        Search for payin refunds. These can relate to [Acquiring](/guide/acquiring/legacy-v1.html#refunds) or [SEPA recalls](/guide/transfers/sepa-recalls.html).

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getPayinrefunds
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: payinId
          in: query
          description: The unique identifier of the payin.
          schema:
            type: integer
            example: 12345
        - name: payinrefundId
          in: query
          description: The unique identifier of the payin refund.
          schema:
            type: integer
            example: 12345
        - name: payinrefundTag
          in: query
          description: |
            Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
            
            Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
          schema:
            type: string
            maxLength: 250
        - name: payinrefundStatus
          in: query
          description: The status of the payin refund.
          schema:
            type: string
            enum:
              - ACCEPTED
              - PENDING
              - CANCELED
              - VALIDATED
        - name: walletId
          in: query
          description: The unique identifier of the Wallet to refund.
          schema:
            type: integer
            example: 12345
        - name: payinrefundDate
          in: query
          description: |
            The date of the payin refund. 
            
            Format: `YYYY-MM-DD`
          schema:
            type: string
            example: "2025-01-05"
        - name: userId
          in: query
          description: The unique identifier of the User who made the refund.
          schema:
            type: integer
            example: 12345
        - name: amount
          in: query
          description: The amount of the refund.
          schema:
            type: string
        - name: currency
          in: query
          description: |
            The currency of the amount. Format: [ISO 4217](/guide/api-basics/data-format.html#currencies).
          schema:
            type: string
            example: "EUR"
        - name: pageNumber
          in: query
          description: |
            The page number, only available on /v1/ endpoints 
          schema:
            type: integer
        - name: cursor
          in: query
          description: |
            Pagination cursor, if you don't pass a cursor, result will start at the first page.
          schema:
            type: string
            example: "da4b9237bacccdf19c0760cab7aec4a8359010b0"
        - name: pageCount
          in: query
          description: |
            The number of items per page, only available on /v1/ endpoints.
          schema:
            type: integer
        - name: sortBy
          in: query
          description: |
            The transaction element you want to sort the list with.
          schema:
            type: string
            default: "createdDate"
        - name: sortOrder
          in: query
          description: |
            The order in which you want to sort the list based on the payin refund's date.
            * **DESC** for descending.
            * **ASC** for ascending.
          schema:
            type: string
            default: DESC
            enum:
              - ASC
              - DESC
        - name: createdDateFrom
          in: query
          description: |
            The creation date from which you want to filter the request result.

            Format: `YYYY-MM-DD HH:mm:ss`. 
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2025-01-01 12:00:00"
        - name: createdDateTo
          in: query
          description: |
            The creation date up to which you want to filter the request result.
            
            Format: `YYYY-MM-DD HH:mm:ss`. 
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2025-01-01 12:00:00"
        - name: updatedDateFrom
          in: query
          description: |
            The modification date from which you want to filter the request result. 
            
            Format: `YYYY-MM-DD HH:mm:ss`
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2025-01-01 12:00:00"
        - name: updatedDateTo
          in: query
          description: |
            The modification date up to which you want to filter the request result. 
            
            Format: `YYYY-MM-DD HH:mm:ss`
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2025-01-01 12:00:00"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  payinrefunds:
                    type: array
                    items:
                      type: object
                      properties:
                        payinrefundId:
                          type: integer
                          description: The universally unique identifier (UUID) of the refund.
                        payinrefundTag:
                          type: string
                        payinrefundStatus:
                          type: string
                          enum:
                            - ACCEPTED
                            - CANCELED
                            - PENDING
                            - VALIDATED
                        walletId:
                          type: integer
                        payinId:
                          type: integer
                        payinrefundDate:
                          type: integer
                        amount:
                          type: string
                        currency:
                          type: string
                        createdDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: |
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2024-04-23 12:34:12"
                        modifiedDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: |
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2024-04-23 12:34:12"
                        totalRows:
                          type: integer
                          description: |
                            The total numbers of objects matching your search, for pagination purposes. Only valued in the first object of the returned page, `null` otherwise.
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
  /v1/payinrefunds/{id}:
    get:
      tags:
        - Payin Refunds
      summary: Get Payin Refund
      description: |
        Retrieve a payin refund.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getPayinrefund
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: id
          in: path
          description: The unique identifier of the payin refund.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  payinrefunds:
                    type: array
                    items:
                      type: object
                      properties:
                        payinrefundId:
                          type: integer
                          description: The unique identifier of the refund.
                        payinrefundTag:
                          type: string
                        payinrefundStatus:
                          type: string
                          enum:
                            - ACCEPTED
                            - CANCELED
                            - PENDING
                            - VALIDATED
                        walletId:
                          type: integer
                        payinId:
                          type: integer
                        payinrefundDate:
                          type: integer
                        amount:
                          type: string
                        currency:
                          type: string
                        createdDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: |
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2024-04-23 12:34:12"
                        modifiedDate:
                          type: string
                          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                          description: |
                            Format: `YYYY-MM-DD HH:mm:ss`
                          example: "2024-04-23 12:34:12"
                        totalRows:
                          type: integer
                          description: |
                            The total numbers of objects matching your search, for pagination purposes. Only valued in the first object of the returned page, `null` otherwise.
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
  /v1/payouts:
    get:
      tags:
        - Payouts
      summary: Search Payouts
      description: |
        Retrieve Payouts that match search criteria. The request must contain at least one of the following inputs: `userId`, `walletId`, `payoutTag`, or `payoutId`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getPayouts
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: payoutTag
          in: query
          description: |
            Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.

            Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
          schema:
            type: string
            maxLength: 250
        - name: walletId
          in: query
          description: The unique identifier of the payout Wallet.
          schema:
            type: integer
            example: 12345
        - name: userId
          in: query
          description: The unique identifier of the payout User.
          schema:
            type: integer
            example: 12345
        - name: sortOrder
          in: query
          description: |
            The order in which you want to sort the list based on the payout's date.
            * **DESC** for descending.
            * **ASC** for ascending.
          schema:
            type: string
            default: DESC
            enum:
              - ASC
              - DESC
        - name: cursor
          in: query
          description: Pagination cursor, if you don't pass a cursor, result will start at the first page.
          schema:
            type: string
            example: "da4b9237bacccdf19c0760cab7aec4a8359010b0"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    post:
      tags:
        - Payouts
      summary: Create Payout
      description: | 
        Create a new payout.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-operation |
        | **[Webhook](/guide/webhooks/introduction.html)** | `payout.create` |
      operationId: postPayout
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - walletId
                - beneficiaryId
                - amount
                - currency
              type: object
              properties:
                payoutTag:
                  type: string
                  maxLength: 250
                  description: |
                    Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html). Highly recommended when initiating payouts to avoid duplicates.

                    **Note**: The maximum number of characters when the `payoutTypeId` set to `1` is **245 characters**.
                walletId:
                  type: integer
                  description: The unique identifier of the debited Wallet.
                payoutTypeId:
                  type: integer
                  description: |
                    The type of payout among the following:
                    * `1` for SEPA Credit Transfer (default)
                    * `2` for SEPA Direct Debit
                    * `3` for SEPA Instant Credit Transfer
                    * `4` for International Transfer
                  enum: [1,2,3,4]
                  default: 1
                bankAccountId:
                  deprecated: true
                  type: integer
                  description: DEPRECATED - Use `beneficiaryId` instead.
                beneficiaryId:
                  type: integer
                  description: The unique identifier of the payout Beneficiary.
                internationalBeneficiaryId:
                  type: string
                  format: uuid
                  description: | 
                    The unique identifier of the international transfer payout Beneficiary. 
                    Required for international transfers.
                beneficiaryValidationId:
                  type: string
                  format: uuid
                  description: |
                    The unique identifier of the beneficiary validation. This is a prerequisite for emitted SEPA Credit Transfers.
                  example: "f8e4a7b2-c1d3-4e5a-8b0f-9c2d1e0a3b5c"
                quoteId:
                  type: string
                  format: uuid
                  description: | 
                    The unique identifier of the quote for international transfer payouts.
                label:
                  type: string
                  maxLength: 140
                  description: | 
                    The payout label that will be displayed on the receiver's bank account.
                    
                    Allowed characters: `a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 / - ? : ( ) . , ' + Space“.` 
                    * Accentuated characters will be replaced by the same characters without accent 
                    * `\n` character are removed
                    * Must not start or end with `/`
                    * Must not contain `//`
                endToEndId:
                  type: string
                  maxLength: 35
                  description: |
                    Unique identification assigned by the final client to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain.

                    Allowed characters: `a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 / - ? : ( ) . , ' + Space“.` 
                    * Accentuated characters will be replaced by the same characters without accent 
                    * `\n` character are removed
                    * Must not start or end with `/`
                    * Must not contain `//`
                amount:
                  type: string
                  format: float
                  description: | 
                    The amount of the payout.
                    * Must be greater than `0`. 
                    * Must be specified as a number with 2 decimals. 
                    
                    For example `180.99` for 180,99 euros and `120.00` for 120 euros.
                  example: "120.67"
                currency:
                  type: string
                  format: ISO 4217
                  description: |
                    The currency of the transfer amount. 
                    
                    Format: [ISO 4217](/guide/api-basics/data-format.html#currencies).
                  example: "EUR"
                supportingFileLink:
                  type: string
                  description: |
                    The HTTPS link of the support file, which may be mandatory in some situations. Learn more in the [SCT processing](/guide/transfers/credit-transfer.html#processing) article.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/payouts/{payoutId}:
    get:
      tags:
        - Payouts
      summary: Get Payout
      description: |
        Retrieve a given Payout.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getPayout
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: payoutId
          in: path
          description: The unique identifier of the Payout.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    delete:
      tags:
        - Payouts
      summary: Cancel Payout
      description: |
        Change payout status to `CANCELED`. A `VALIDATED` payout can't be canceled.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: deletePayout
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: payoutId
          in: path
          description: The unique identifier of the Payout.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/payoutRefunds:
    post:
      tags:
        - Payout Refunds
      summary: Create Payout Refund
      description: |
        This request is used to emit an [SCT Recall](/guide/transfers/sepa-recalls.html#emitting-sct-recalls) or [refund an SDDR Core](/guide/transfers/direct-debit.html#refund-management).

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | `payoutRefund.create` |
      operationId: postPayoutRefund
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - payoutId
                - reasonCode
              type: object
              properties:
                payoutId:
                  type: string
                  description: The unique identifier of the payout for which the recall or refund is to be made.
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html). 
                payoutRefundTag:
                  type: string
                  maxLength: 250
                  description: |
                    Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
                    
                    Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
                requestAmount:
                  type: number
                  description: The amount of the recall or refund request. Defaults to the initial Payout amount.
                  format: float
                  example: 100.23
                requestCurrency:
                  type: string
                  description: The currency of the recall or refund request. Defaults to the initial Payout currency.
                  default: Initial Payout currency
                  example: "EUR"
                requestComment: 
                  type: string
                  maxLength: 105
                  description: Comment for the refund request.
                  example: "Fraudulent transaction detected"
                reasonCode:
                  type: string
                  description: |
                    The reason for the recall, as listed in the [Types of Recalls](/guide/transfers/sepa-recalls.html#types-of-recalls-reasoncode) article.
                    
                    Can only be `MD06` or `MD01` for SDDR Core refunds.
                  enum: [DUPL, TECH, FRAD, CUST, AM09, AC03, MD01, MD06]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutRefundResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/payoutRefunds/{payoutRefundId}:
    get:
      tags:
        - Payout Refunds
      summary: Get Payout Refund
      description: |
        Retrieve a given Payout Refund with its `id`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A|
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getPayoutRefund 
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: payoutRefundId
          required: true
          in: path
          description: The unique identifier of the payout refund.
          schema:
            type: string
            example: "12345"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutRefundResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write 

  /v1/massPayouts:
    post:
      tags:
        - Payouts 
      summary: Create Mass Payout   
      description: |            
        Create a new Mass Payout.

        |     |     |
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-operation |
        | **[Webhook](/guide/webhooks/introduction.html)** | `payout.create` |
      operationId: postMassPayout
      #parameters:
      #  - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - vopOptOut
                - payouts
                - massPayoutTag
              properties:
                massPayoutTag:
                  type: string
                  maxLength: 250
                  description: |
                    Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.

                    The value **must be unique**, as Treezor uses this field to verify the uniqueness of the request.

                    Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
                  example: "ref-pay-nov-2024"
                vopOptOut:
                  type: boolean
                  description: |
                    Indicates that you have collected the end users' consent to opt out of the [Verification of Payee](/guide/overview/glossary.html#verification-of-payee-vop) service.
                payouts:
                  type: array
                  maxItems: 1000
                  minItems: 2 
                  items:
                    type: object
                    description: The list of payouts to be created in the batch.
                    required:
                      - payoutTag
                      - walletId
                      - beneficiaryId
                      - amount
                      - currency
                    properties:
                      payoutTag:
                        type: string
                        maxLength: 250
                        description: |
                          Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.

                          Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
                      accessTag:
                        type: string
                        maxLength: 250
                        description: |
                          A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                      walletId:
                        type: integer
                        description: The unique identifier of the debited Wallet. Must be the same for all the payouts of the batch.
                      payoutTypeId:
                        type: integer
                        description: |
                          The type of payout. As of today, only SEPA Credit Transfer (`1`) is supported for Mass Payouts.
                        enum: [1]
                        default: 1
                      beneficiaryId:
                        type: integer
                        description: The unique identifier of the payout Beneficiary.
                      label:
                        type: string
                        maxLength: 140
                        description: |
                          The payout label that will be displayed on the receiver's bank account.

                          Allowed characters: `a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 / - ? : ( ) . , ' + Space“.`
                          * Accentuated characters will be replaced by the same characters without accent
                          * `\n` character are removed
                          * Must not start or end with `/`
                          * Must not contain `//`
                      endToEndId:
                        type: string
                        maxLength: 35
                        description: |
                          Unique identification assigned by the final client to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain.

                          Allowed characters: `a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 / - ? : ( ) . , ' + Space“.`
                          * Accentuated characters will be replaced by the same characters without accent
                          * `\n` character are removed
                          * Must not start or end with `/`
                          * Must not contain `//`
                      amount:
                        type: string
                        format: float
                        description: |
                          The amount of the payout.
                          * Must be greater than `0`.
                          * Must be specified as a number with 2 decimals.

                          For example `180.99` for 180,99 euros and `120.00` for 120 euros.
                        example: "120.67"
                      currency:
                        type: string
                        format: ISO 4217
                        description: |
                          The currency of the transfer amount.

                          Format: [ISO 4217](/guide/api-basics/data-format.html#currencies).
                        example: "EUR"
                      supportingFileLink:
                        type: string
                        description: The link of the support file, which may be mandatory in some situations. Learn more in the [SCT processing](/guide/transfers/credit-transfer.html#processing) article.
      responses:  
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  massPayoutId:
                    type: string
                    format: uuid
                    description: The unique identifier of the mass payout batch.
                    example: "8b9dacf4-6acf-407b-953c-fcbb21355c1c"
                  massPayoutTag:
                    type: string
                    maxLength: 250
                    description: |
                      Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.

                      Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
                    example: "ref-pay-nov-2024"
                  vopOptOut: 
                    type: boolean
                    description: |
                      Indicates that you have collected the end users' consent to opt out of the [Verification of Payee](/guide/overview/glossary.html#verification-of-payee-vop) service.
                  createdDate:
                    description: |
                      The date and time at which the mass payout batch was created. Format: `YYYY-MM-DD HH:mm:ss`
                    example: "2024-04-24 08:55:26"
        '400':
          $ref: '#/components/responses/BadRequestError' 
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/massPayouts/{massPayoutId}:
    get:
      tags:
        - Payouts
      summary: Get Mass Payout
      description: |
        Retrieve the status of all the payouts of a given mass payout batch.

        |   |   |
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getMassPayoutStatus
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: massPayoutId
          in: path
          description: The unique identifier of the mass payout batch.
          required: true
          schema:
            type: string
            format: uuid
            example: "8b9dacf4-6acf-407b-953c-fcbb21355c1c"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MassPayoutObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security: 
        - OAuth2:
          - read_only

  /v1/recallRs:
    get:
      tags:
        - Recalls
      summary: Get Recalls or RRO
      description: |
        Retrieve recalls or RROs.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getRecallRs
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: pageCount
          in: query
          description: |
            The number of items per page, only available on /v1/ endpoints
          schema:
            type: integer
        - name: pageNumber
          in: query
          description: |
            The page number, only available on /v1/ endpoints
          schema:
            type: integer
        - name: filter
          in: query
          description: |
            List of available filters:
            - id
            - recallRSepaMessageId
            - cxlId
            - statusId
            - reasonCode
            - clientId
            - userId
            - walletId
            - sctrId
            - receivedDate
            - frozenWalletFollowingRecallr
            - createdDate
            - inError
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  recallrs:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        recallRSepaMessageId:
                          type: integer
                        cxlId:
                          type: integer
                        statusId:
                          type: integer
                          description: |
                            The status of the recall. See [Status](/guide/transfers/sepa-recalls.html#status-statusid) for more information.
                          enum: [1,2,3,4,5,6,7]
                        statusLabel:
                          type: string
                          description: |
                            The status of the recall. See [Status](/guide/transfers/sepa-recalls.html#status-statusid) for more information.
                          enum:
                            - PENDING
                            - PENDING PAYIN REFUND CREATED
                            - PENDING ANSWER REQUESTED
                            - ACCEPTED
                            - REJECTED
                            - CANCELED
                            - IN ERROR
                        reasonCode:
                          type: string
                          description: | 
                            The type of recall. See [Types](/guide/transfers/sepa-recalls.html#types-of-recalls-reasoncode) for more information.
                          enum: [DUPL, TECH, FRAD, CUST, AM09, AC03]
                        additionalInformation:
                          type: string
                        clientId:
                          type: integer
                        userId:
                          type: integer
                        userTypeId:
                          type: integer
                        userName:
                          type: string
                        userStatusId:
                          type: integer
                        walletId:
                          type: integer
                        walletStatusId:
                          type: integer
                        walletActivationDate:
                          type: string
                        walletDesactivationDate:
                          type: string
                        sctrAmount:
                          type: string
                        sctrSettlementDate:
                          type: string
                        sctrDbtrIBAN:
                          type: string
                        sctrDbtrBIC:
                          type: string
                        sctrDbtrName:
                          type: string
                        responseSepaMessageId:
                          type: integer
                        receivedDate:
                          type: string
                        payinId:
                          type: integer
                        payinRefundId:
                          type: integer
                        responseType:
                          type: integer
                        negativeResponseReasonCode:
                          type: string
                          enum:
                            - CUST
                            - LEGL
                            - AC04
                            - NOOR
                            - AM04
                            - NOAS
                            - ARDT
                        negativeResponseAdditionalInformation:
                          type: string
                        responseComment:
                          type: string
                        boResponse:
                          type: boolean
                        frozenWalletFollowingRecallr:
                          type: boolean
                        automaticResponse:
                          type: string
                        comment:
                          type: string
                        fraudConfirmed:
                          type: boolean
                        partialRefund:
                          type: boolean
                        inError:
                          type: boolean
                        createdDate:
                          type: string
                        updatedDate:
                          type: string
        '401':
          description: Unauthorized credentials
          content: {}
        '403':
          description: Forbidden action
          content: {}
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          description: Internal error
          content: {}
      security:
        - OAuth2:
          - read_only
          - read_write
  /v1/recallRs/{recallId}:
    get:
      tags:
        - Recalls
      summary: Get Recall or RRO
      description: | 
        Retrieve a given recall or RRO.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getRecallR
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: recallId
          in: path
          required: true
          description: |
            The unique identifier of the recall.
          schema:
            type: string
            example: "12345"
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: pageCount
          in: query
          description: |
            The number of items per page, only available on /v1/ endpoints
          schema:
            type: integer
        - name: pageNumber
          in: query
          description: |
            The page number, only available on /v1/ endpoints
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  recallrs:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        recallRSepaMessageId:
                          type: integer
                        cxlId:
                          type: integer
                        statusId:
                          type: integer
                          description: |
                            The status of the recall. See [Status](/guide/transfers/sepa-recalls.html#status-statusid) for more information.
                          enum: [1,2,3,4,5,6,7]
                        statusLabel:
                          type: string
                          description: |
                            The status of the recall. See [Status](/guide/transfers/sepa-recalls.html#status-statusid) for more information.
                          enum:
                            - PENDING
                            - PENDING PAYIN REFUND CREATED
                            - PENDING ANSWER REQUESTED
                            - ACCEPTED
                            - REJECTED
                            - CANCELED
                            - IN ERROR
                        reasonCode:
                          type: string
                          description: | 
                            The type of recall. See [Types](/guide/transfers/sepa-recalls.html#types-of-recalls-reasoncode) for more information.
                          enum: [DUPL, TECH, FRAD, CUST, AM09, AC03]
                        additionalInformation:
                          type: string
                        clientId:
                          type: integer
                        userId:
                          type: integer
                        userTypeId:
                          type: integer
                        userName:
                          type: string
                        userStatusId:
                          type: integer
                        walletId:
                          type: integer
                        walletStatusId:
                          type: integer
                        walletActivationDate:
                          type: string
                        walletDesactivationDate:
                          type: string
                        sctrAmount:
                          type: string
                        sctrSettlementDate:
                          type: string
                        sctrDbtrIBAN:
                          type: string
                        sctrDbtrBIC:
                          type: string
                        sctrDbtrName:
                          type: string
                        responseSepaMessageId:
                          type: integer
                        receivedDate:
                          type: string
                        payinId:
                          type: integer
                        payinRefundId:
                          type: integer
                        responseType:
                          type: integer
                        negativeResponseReasonCode:
                          type: string
                          enum:
                            - CUST
                            - LEGL
                            - AC04
                            - NOOR
                            - AM04
                            - NOAS
                            - ARDT
                        negativeResponseAdditionalInformation:
                          type: string
                        responseComment:
                          type: string
                        boResponse:
                          type: boolean
                        frozenWalletFollowingRecallr:
                          type: boolean
                        automaticResponse:
                          type: string
                        comment:
                          type: string
                        fraudConfirmed:
                          type: boolean
                        partialRefund:
                          type: boolean
                        inError:
                          type: boolean
                        createdDate:
                          type: string
                        updatedDate:
                          type: string
        '401':
          description: Unauthorized credentials
          content: {}
        '403':
          description: Forbidden action
          content: {}
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          description: Internal error
          content: {}
      security:
        - OAuth2:
          - read_only
          - read_write
  /v1/recallRs/{recallId}/response:
    put:
      tags:
        - Recalls
      summary: Respond to Recall or RRO
      description: |
        Respond to a Recall or a RRO.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | `payinRefund.update` |
      operationId: putRecallR
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: recallId
          in: path
          description: The unique identifier of the recall.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              required:
                - responseType
              type: object
              properties:
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                responseType:
                  type: integer
                  description: | 
                    Response to the received recall request. The recall request can be:
                    * `1` – Accepted and generates a positive response to the originating bank.
                    * `0` – Refused and generates a negative response to the originating bank.
                  enum:
                    - 0
                    - 1
                negativeResponseReasonCode:
                  type: string
                  description: |
                    Reason of negative response type. Required if `responseType` is false.
                    This field is non case sensitive.
                  enum:
                    - CUST
                    - LEGL
                    - AC04
                    - NOOR
                    - AM04
                    - NOAS
                    - ARDT
                negativeResponseAdditionalInformation:
                  type: string
                  description: |
                    Free field to add more informations of a negative response type.
                responseComment:
                  type: string
                  description: |
                    Free field to add more informations regardless the response type.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  recallrs:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        recallRSepaMessageId:
                          type: integer
                        cxlId:
                          type: integer
                        statusId:
                          type: integer
                          description: |
                            The status of the recall. See [Status](/guide/transfers/sepa-recalls.html#status-statusid) for more information.
                          enum: [1,2,3,4,5,6,7]
                        statusLabel:
                          type: string
                          description: |
                            The status of the recall. See [Status](/guide/transfers/sepa-recalls.html#status-statusid) for more information.
                          enum:
                            - PENDING
                            - PENDING PAYIN REFUND CREATED
                            - PENDING ANSWER REQUESTED
                            - ACCEPTED
                            - REJECTED
                            - CANCELED
                            - IN ERROR
                        reasonCode:
                          type: string
                          description: | 
                            The type of recall. See [Types](/guide/transfers/sepa-recalls.html#types-of-recalls-reasoncode) for more information.
                          enum: [DUPL, TECH, FRAD, CUST, AM09, AC03]
                        additionalInformation:
                          type: string
                        clientId:
                          type: integer
                        userId:
                          type: integer
                        userTypeId:
                          type: integer
                        userName:
                          type: string
                        userStatusId:
                          type: integer
                        walletId:
                          type: integer
                        walletStatusId:
                          type: integer
                        walletActivationDate:
                          type: string
                        walletDesactivationDate:
                          type: string
                        sctrAmount:
                          type: string
                        sctrSettlementDate:
                          type: string
                        sctrDbtrIBAN:
                          type: string
                        sctrDbtrBIC:
                          type: string
                        sctrDbtrName:
                          type: string
                        responseSepaMessageId:
                          type: integer
                        receivedDate:
                          type: string
                        payinId:
                          type: integer
                        payinRefundId:
                          type: integer
                        responseType:
                          type: integer
                        negativeResponseReasonCode:
                          type: string
                          enum:
                            - CUST
                            - LEGL
                            - AC04
                            - NOOR
                            - AM04
                            - NOAS
                            - ARDT
                        negativeResponseAdditionalInformation:
                          type: string
                        responseComment:
                          type: string
                        boResponse:
                          type: boolean
                        frozenWalletFollowingRecallr:
                          type: boolean
                        automaticResponse:
                          type: string
                        comment:
                          type: string
                        fraudConfirmed:
                          type: boolean
                        partialRefund:
                          type: boolean
                        inError:
                          type: boolean
                        createdDate:
                          type: string
                        updatedDate:
                          type: string
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/recall-sct-inst/{sctInstId}/{recallId}:
    get:
      tags:
        - Recalls
      summary: Get SCT Inst Recall
      operationId: getRecallSctInst
      description: |
        Retrieve an SCT Inst Recall.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: sctInstId
          in: path
          required: true
          schema:
            type: string
            example: "12345"
          description: The unique identifier of the initial SCT Inst.
        - name: recallId
          in: path
          required: true
          schema:
            type: string
            example: "12345"
          description: The unique identifier of the recall.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  recalls:
                    type: array
                    items:
                      type: object
                      properties:
                        recallId:
                          type: string
                        creationDateTIme:
                          type: string
                        statusLabel:
                          type: string
                          description: |
                            The status of the recall. See [Status](/guide/transfers/sepa-recalls.html#status-statuslabel) for more information.
                          enum:
                            - PENDING
                            - PENDING_REJECTED_WAITING_ACK
                            - PENDING_ACCEPTED_WAITING_ACK
                            - ACCEPTED
                            - REJECTED
                        cxlId:
                          type: string
                        reasonCode:
                          type: string
                          description: | 
                            The type of recall. See [Types](/guide/transfers/sepa-recalls.html#types-of-recalls-reasoncode) for more information.
                          enum: [DUPL, TECH, FRAD, CUST, AM09, AC03]
                        additionalInformation:
                          type: string
                        sctrDbtrIBAN:
                          type: string
                        sctrDbtrBIC:
                          type: string
                        sctrDbtrName:
                          type: string
                        sctrDbtrAddress:
                          type: string
                        sctrDbtrCountry:
                          type: string
                        sctrCdtrIBAN:
                          type: string
                        sctrCdtrBIC:
                          type: string
                        sctrCdtrName:
                          type: string
                        sctrCdtrAddress:
                          type: string
                        sctrCdtrCountry:
                          type: string
                        sctrMsgId:
                          type: string
                        sctrInstrId:
                          type: string
                        sctrTxId:
                          type: string
                          description: The unique identifier of the transaction.
                        sctrE2EID:
                          type: string
                        sctrAmount:
                          type: string
                        sctrSettlementDate:
                          type: string
                        sctrRemittanceInformation:
                          type: string
                        sctrTrzId:
                          type: string
                        sctrExternalId:
                          type: string
                        clientId:
                          type: integer
                        userId:
                          type: integer
                        walletId:
                          type: integer
                        receivedDate:
                          type: string
                        payinRefundId:
                          type: integer
                        payinRefundUuid:
                          type: string
                        responseType:
                          type: integer
                        negativeResponseReasonCode:
                          type: string
                          description: The [type of Recall Rejection](/guide/transfers/sepa-recalls.html#types-of-recalls-reasoncode).
                          enum: ["NOOR", "ARDT", "AC04", "NOAS", "CUST", "AM04", "LEGL"]
                        negativeResponseAdditionalInformation:
                          type: string
                        responseComment:
                          type: string
                        automaticResponse:
                          type: string
                        createdDate:
                          type: string
                        updatedDate:
                          type: string
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                    example: "item not found"
                  details:
                    type: string
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          description: Internal error
          content: {}
      security:
        - OAuth2:
          - read_only
          - read_write
  /v1/recall-sct-inst/{sctInstId}/{recallId}/response:
    put:
      tags:
        - Recalls
      summary: Respond to SCT Inst Recall
      operationId: putRecallSctInst
      description: | 
        Provide your decision following an SCT Inst Recall.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | `payinRefund.update` |
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: sctInstId
          in: path
          required: true
          schema:
            type: string
            example: "12345"
          description: The unique identifier of the initial SCT Inst.
        - name: recallId
          in: path
          required: true
          schema:
            type: string
            example: "12345"
          description: The unique identifier of the recall.
      requestBody:
        content:
          application/json:
            schema:
              required:
                - responseType
              type: object
              properties:
                responseType:
                  type: integer
                  description: |
                    Indicates whether to accept (`1`) or decline (`0`) the recall.
                  enum: [0,1]
                negativeResponseAdditionalInformation:
                  type: string
                  description: | 
                    Additional information for rejecting a Recall. May be mandatory in some situations, learn more in the [Reject a Recall](/guide/transfers/sepa-recalls.html#reject-a-recall-2) article.
                negativeResponseReasonCode:
                  type: string
                  description: The [type of Recall Rejection](/guide/transfers/sepa-recalls.html#types-of-recalls-reasoncode). This field is mandatory if the `responseType` is `0`.
                  enum: ["NOOR", "ARDT", "AC04", "NOAS", "CUST", "AM04", "LEGL"]
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  recallID:
                    type: string
                    example: "a14d728e-b02a-43c2-9b2d-a394fc45xx1d"
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                  details:
                    type: string
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/taxResidences:
    get:
      tags:
        - User Tax Residences
      summary: Search Tax Residences
      operationId: getTaxresidences
      description: | 
        Retrieve Tax Residences that match your search criteria.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: taxResidenceId
          in: query
          description: The unique identifier of the Tax Residence.
          schema:
            type: integer
            example: 12345
        - name: userId
          in: query
          description: The unique identifier of the User.
          schema:
            type: integer
            example: 12345
        - name: pageNumber
          in: query
          description: |
            The page number, only available on /v1/ endpoints 
          schema:
            type: integer
        - name: pageCount
          in: query
          description: |
            The number of items per page, only available on /v1/ endpoints  
          schema:
            type: integer
        - name: sortBy
          in: query
          description: |
            The transaction element you want to sort the list with.
          schema:
            type: string
            default: "createdDate"
        - name: sortOrder
          in: query
          description: |
            The order you want to sort the list.
            * **DESC** for descending.
            * **ASC** for ascending.
          schema:
            type: string
            default: DESC
            enum:
              - ASC
              - DESC
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/TaxResidenceObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    post:
      tags:
        - User Tax Residences
      summary: Create Tax Residence 
      operationId: postTaxresidence
      description: |
        Create a new Tax Residence.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - userId
                - country
                - liabilityWaiver
              type: object
              properties:
                userId:
                  type: integer
                  description: The unique identifier of the user.
                country: 
                  type: string
                  description: The country of the resident.
                taxPayerId:
                  type: string
                  description: |
                    The Tax Identification Number (TIN) or Tax Code of the User.
                    
                    This field is mandatory if:
                    * The country of the resident is `US`
                    * The tax residence `country` is `IT`. 
                    
                    Optional otherwise.
                liabilityWaiver:
                  type: boolean
                  description: |
                    Must be set to true if the `taxPayerId` is empty or null, and set to false otherwise.
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/TaxResidenceObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/taxResidences/{taxResidenceId}:
    get:
      tags:
        - User Tax Residences
      operationId: getTaxresidence
      summary: Get Tax Residence
      description: | 
        Retrieve a Tax Residence based on its `id`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: taxResidenceId
          in: path
          description: The unique identifier of the TaxResidence.
          required: true
          schema:
            type: integer
            example: 12345
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/TaxResidenceObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    put:
      tags:
        - User Tax Residences
      summary: Update Tax Residence
      operationId: putTaxresidence
      description: | 
        Modify an existing Tax Residence.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: taxResidenceId
          in: path
          description: The unique identifier of the TaxResidence
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: integer
                  description: The unique identifier of the user.
                country: 
                  type: string
                  description: The country of the resident.
                taxPayerId:
                  type: string
                  description: |
                    The Tax Identification Number (TIN) or Tax Code of the User.
                    
                    This field is mandatory if:
                    * The country of the resident is `US`
                    * The tax residence `country` is `IT`. 
                    
                    Optional otherwise.
                liabilityWaiver:
                  type: boolean
                  description: |
                    Must be set to true if the `taxPayerId` is empty or null, and set to false otherwise.
      responses:
        '200':
          description: OK
          content:
            application/json: 
              schema:
                $ref: '#/components/schemas/TaxResidenceObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
    delete:
      tags:
        - User Tax Residences
      summary: Delete a residence
      operationId: deleteTaxresidence
      description: |
        Delete an existing Tax Residence. 
        
        Doing so populates the `deletedDate` field and sets `isDeleted` to `true`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: taxResidenceId
          in: path
          description: The unique identifier of the Tax Residence
          required: true
          schema:
            type: integer
            example: 12345
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/TaxResidenceObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/transactions:
    get:
      tags:
        - Transactions
      summary: Search Transactions
      description: |
        Retrieve Transactions that match search criteria. The request must contain at least one of the following inputs: `walletId`, `transactionId`, `executionDate`, `valueDate`

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getTransactions
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: transactionId
          in: query
          description: The unique identifier of the transaction.
          schema:
            type: integer
            example: 12345
        - name: transactionType
          in: query
          description: |
            Names of the transaction types. Please refer to the [Transactions](/guide/wallets/transactions.html#transaction-types-transactiontype) article for the list of possible values.
          schema:
            type: string
            enum:
              - Payin
              - Payout
              - Transfer
              - Payin Refund
              - Card Transaction
              - Payout Refund
              - Payin Acquiring
              - Payin Refund Acquiring
              - SCTR Inst
              - Payin SCT Instant Recall
              - Payout SCT Instant Emit
              - Payin SCT Instant Emit Recall
              - Credit Transfer Returned
              - Check Payin
              - SDDE
              - SDDR
              - SDDR Reversal
              - SCTR Recall
              - Check Refund
              - SCTR
              - Credit International Transfer
        - name: transactionTypeId
          in: query
          description: |
            The Id of the transaction types. Please refer to the [Transactions](/guide/wallets/transactions.html#transaction-types-transactiontype) article for the list of possible values.
          schema:
            type: integer
            enum: [1,2,3,5,10,11,13,14,15,17,18,19,20,21,22,23,24,25,26,27,28]
        - name: walletId
          in: query
          description: Unique identifier of the transactions Wallet.
          schema:
            type: integer
            example: 12345
        - name: userId
          in: query
          description: Unique identifier of the transactions User.
          schema:
            type: integer
            example: 12345
        - name: name
          in: query
          description: The name of the transaction.
          schema:
            type: string
            example: 266924b3-1f0c-48c0-b166-42c227a5a069
        - name: description
          in: query
          description: The description of the transaction.
          schema:
            type: string
        - name: amount
          in: query
          description: The amount of the transaction.
          schema:
            type: string
            format: float
            example: "25.55"
        - name: currency
          in: query
          description: |
            The currency of the transaction amount currency. Format: [ISO 4217](/guide/api-basics/data-format.html#currencies).
          schema:
            type: string
            example: "EUR"
        - name: valueDate
          in: query
          description: |
            The value date of the transaction (date applied for the payment).

            Format: `YYYY-MM-DD`
          schema:
            type: string
            format: date
            example: "2025-01-01"
        - name: executionDate
          in: query
          description: |
            Date of the execution of the transaction.

            Format: `YYYY-MM-DD`
          schema:
            type: string
            format: date
            example: "2025-01-01"
        - name: pageNumber
          in: query
          description: |
            The page number, only available on /v1/ endpoints 
          schema:
            type: integer
        - name: pageCount
          in: query
          description: |
            The number of items per page, only available on /v1/ endpoints  
          schema:
            type: integer
        - name: sortBy
          in: query
          description: |
            The transaction element you want to sort the list with.
          schema:
            type: string
            default: "createdDate"
        - name: sortOrder
          in: query
          description: |
            The order you want to sort the list.
            * **DESC** for descending.
            * **ASC** for ascending.
          schema:
            type: string
            default: DESC
            enum:
              - ASC
              - DESC
        - name: createdDateFrom
          in: query
          description: |
            The creation date from which you want to filter the request result.
            
            Format: `YYYY-MM-DD HH:mm:ss`
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2025-01-01 12:00:00"
        - name: createdDateTo
          in: query
          description: |
            The creation date up to which you want to filter the request result.

            Format: `YYYY-MM-DD HH:mm:ss`
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2025-01-01 12:00:00"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
  /v1/transactions/{transactionId}:
    get:
      tags:
        - Transactions
      summary: Get Transaction
      description: |
        Retrieve a transaction.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getTransaction
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: transactionId
          in: path
          description: The unique identifier of the Transaction.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
  /v1/transfers:
    get:
      tags:
        - Transfers
      summary: Search Transfers
      description: |
        Retrieve the list of transfers for at least one of those inputs:
        `walletId`, `beneficiaryWalletId`, `userId`, `beneficiaryUserId`, `transferId`, `transferTag`

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getTransfers
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: transferId
          in: query
          description: The unique identifier of the Transfer.
          schema:
            type: integer
            example: 12345
        - name: transferTag
          in: query
          description: |
            Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.

            Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
          schema:
            type: string
            maxLength: 250
        - name: transferStatus
          in: query
          description: |
            The status of the Transfer.
          schema:
            type: string
            enum: 
              - CANCELED
              - PENDING
              - VALIDATED
        - name: walletId
          in: query
          description: The unique identifier of the debited Wallet.
          schema:
            type: integer
            example: 12345
        - name: beneficiaryWalletId
          in: query
          description: The unique identifier of the credited Wallet.
          schema:
            type: integer
            example: 12345
        - name: userId
          in: query
          description: The unique identifier of the owner of the debited Wallet.
          schema:
            type: integer
            example: 12345
        - name: beneficiaryUserId
          in: query
          description: The unique identifier of the owner of the credited Wallet.
          schema:
            type: integer
            example: 12345
        # - name: transferDate
        #   in: query
        #   deprecated: true
        #   description: |
        #     The date and time of the transfer. Format: YYYY-MM-DD HH:MM:SS
        #   schema:
        #     type: string
        #     format: date-time
        - name: amount
          in: query
          description: The amount of the Transfer.
          schema:
            type: string
        - name: currency
          in: query
          description: |
            The currency of the Transfer amount. Format: [ISO 4217](/guide/api-basics/data-format.html#currencies).
          example: "EUR"
          schema:
            type: string
            format: ISO 4217
        - name: transferTypeId
          in: query
          description: |
            The type of the Transfer:
            * `1` – Wallet to wallet 
            * `2` – Card transaction
            * `3` – Client fees
            * `4` – Credit note
          schema:
            type: integer
            enum: [1,2,3,4]
        - name: pageNumber
          in: query
          description: |
            The page number, only available on /v1/ endpoints 
          schema:
            type: integer
        - name: pageCount
          in: query
          description: |
            The number of items per page, only available on /v1/ endpoints  
          schema:
            type: integer
        - name: sortBy
          in: query
          description: |
            The transaction element you want to sort the list with.
          schema:
            type: string
            default: "createdDate"
        - name: sortOrder
          in: query
          description: |
            The order you want to sort the list.
            * **DESC** for descending.
            * **ASC** for ascending.
          schema:
            type: string
            default: DESC
            enum:
              - ASC
              - DESC
        - name: createdDateFrom
          in: query
          description: |
            The creation date from which you want to filter the request result.
            
            Format: `YYYY-MM-DD HH:mm:ss`. 
          example: "2024-12-04 12:44:54"
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
        - name: createdDateTo
          in: query
          description: |
            The creation date up to which you want to filter the request result.
            
            Format: `YYYY-MM-DD HH:mm:ss`. 
          example: "2024-12-04 12:44:54"
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
        - name: updatedDateFrom
          in: query
          description: |
            The modification date from which you want to filter the request result. 
            
            Format: `YYYY-MM-DD HH:mm:ss`. 
          example: "2024-12-04 12:44:54"
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
        - name: updatedDateTo
          in: query
          description: |
            The modification date up to which you want to filter the request result. 
            
            Format: `YYYY-MM-DD HH:mm:ss`. 
          example: "2024-12-04 12:44:54"
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    post:
      tags:
        - Transfers
      summary: Create Transfer
      description: | 
        Create a new Wallet-to-Wallet transfer.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session if the `beneficiaryWalletId` belongs to the current user. Per-operation otherwise. |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`transfer.create`](/guide/transfers/events.html#transfer-create) |
      operationId: postTransfers
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - walletId
                - beneficiaryWalletId
                - amount
                - currency
              type: object
              properties:
                transferTag:
                  type: string
                  description: |
                    Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.

                    Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
                  maxLength: 250
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                walletId:
                  type: integer
                  description: The debited Wallet unique identifier.
                beneficiaryWalletId:
                  type: integer
                  description: The credited Wallet unique identifier.
                amount:
                  type: number
                  format: float
                  description: The amount of the Transfer.
                  example: 23.88
                currency:
                  type: string
                  format: ISO 4217
                  description: | 
                    The currency of the Transfer in [ISO 4217](/guide/api-basics/data-format.html#currencies) format. Debited wallet and credited wallet must share same currency.
                  example: "EUR"
                label:
                  type: string
                  description: | 
                    The label of the transfer, to display on the receiver's statement for instance.
                  maxLength: 140
                transferTypeId:
                  type: integer
                  description: |
                    The type of the Transfer:
                    * `1` – Wallet to wallet 
                    * `3` – Client fees
                    * `4` – Credit note
                  enum: [1,3,4]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/transfers/{transferId}:
    get:
      tags:
        - Transfers
      summary: Get Transfer
      description: | 
        Retrieve a transfer using its `id`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getTransfer
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: transferId
          in: path
          description: The unique identifier of the Transfer.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    delete:
      tags:
        - Transfers
      summary: Cancel Transfer
      description: |
        Change status of the Transfer to `CANCELED`. 
        
        Only transfers whose status is `PENDING` can be canceled.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`transfer.cancel`](/guide/transfers/events.html#transfer-cancel) |
      operationId: deleteTransfer
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: transferId
          in: path
          description: The unique identifier of the Transfer.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/users:
    get:
      tags:
        - Users
      summary: Search Users
      description: |
        Retrieve Users matching your search criteria.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getUsers
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: userId
          in: query
          description: The unique identifier of the User.
          schema:
            type: integer
            example: 12345
        - name: userTypeId
          in: query
          description: The type of the user.
          schema:
            type: integer
            enum: [1, 2, 3, 4]
        - name: userStatus
          in: query
          description: The status of the user.
          schema:
            type: string
            enum:
              - CANCELED
              - PENDING
              - VALIDATED
        - name: userTag
          in: query
          description: |
            Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
            
            Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
          schema:
            type: string
            maxLength: 250
        - name: specifiedUSPerson
          in: query
          description: |
            You may read more about who is considered a US Person in the [dedicated article](/guide/users/tax-residence.html).
          schema:
            type: integer
            enum: [0, 1]
        - name: controllingPersonType
          in: query
          description: Type of relationship
          schema:
            type: integer
            enum: [0, 1, 2, 3]
        - name: employeeType
          in: query
          description: Type of user's role
          schema:
            type: integer
            enum: [0, 1, 2]
        - name: email
          in: query
          description: User's email address (must be valid).
          schema:
            type: string
        - name: name
          in: query
          description: |
            The name of the user. When filtering users by name, this field takes into account the `firstname`, `lastname`, and `email` attributes.

            This is a non-strict search, that returns users with values close to the one entered.
          schema:
            type: string
        - name: legalName
          in: query
          description: |
            The name of the legal entity. When filtering users by name, this field only takes into account the `legalName` attribute.

            This is a non-strict search, that returns users with values close to the one entered.
          schema:
            type: string
        - name: parentUserId
          in: query
          description: Unique identifier of the parent of the user.
          schema:
            type: integer
        - name: pageNumber
          in: query
          description: |
            The page number, only available on /v1/ endpoints 
          schema:
            type: integer
        - name: pageCount
          in: query
          description: |
            The number of items per page, only available on /v1/ endpoints  
          schema:
            type: integer
        - name: sortBy
          in: query
          description: |
            The transaction element you want to sort the list with.
          schema:
            type: string
            default: "createdDate"
        - name: sortOrder
          in: query
          description: |
            The order you want to sort the list.
          schema:
            type: string
            default: DESC
            enum:
              - ASC
              - DESC
        - name: createdDateFrom
          in: query
          description: |
            The creation date from which you want to filter the request result.

            Format: `YYYY-MM-DD HH:mm:ss`
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2025-01-01 12:00:00"
        - name: createdDateTo
          in: query
          description: |
            The creation date up to which you want to filter the request result.

            Format: `YYYY-MM-DD HH:mm:ss`
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2025-01-01 12:00:00"
        - name: updatedDateFrom
          in: query
          description: |
            The modification date from which you want to filter the request result. 
            
            Format: `YYYY-MM-DD HH:mm:ss`. 
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2025-01-01 12:00:00"
        - name: updatedDateTo
          in: query
          description: |
            The modification date up to which you want to filter the request result. 
            
            Format: `YYYY-MM-DD HH:mm:ss`. 
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2025-01-01 12:00:00"
        - name: _embed
          in: query
          description: |
            Embeds related [User Relationships](/guide/users/relationships.html) data directly in the response. 
            
            Accepts a comma-separated list of values. When used, each User object in the response includes an `embed` object containing the requested relationship data.

            The embedded relationships are limited to 10 items per direction. Use `has_more` in the response to determine if additional relationships exist.
          schema:
            type: string
            enum:
              - ascending_relationships
              - descending_relationships
              - relationships
          example: "ascending_relationships,descending_relationships"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    post:
      tags:
        - Users
      summary: Create User
      description: | 
        Create a new physical user or legal entity.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `legal`, `admin` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`user.create`](/guide/users/events.html#user-create) |
      operationId: postUsers
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - userTypeId
                - specifiedUSPerson
                - email
              type: object
              properties:
                userTypeId:
                  type: integer
                  description: |
                    The type of the user. May be one of the following:
                    * `1` – Natural person (default)
                    * `2` – Business entity
                    * `3` – Non - governmental organization
                    * `4` – Governmental organization

                    You may read more about [Users](/guide/users/introduction.html)
                  enum: [1, 2, 3, 4]
                  default: 1
                userTag:
                  type: string
                  maxLength: 250
                  description: |
                    Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
                    
                    Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                parentUserId:
                  type: integer
                  description: The unique identifier of the parent user (if any).
                parentType:
                  type: string
                  description: |
                    The type of relationship between the parent and the current users.

                    You may read more about [parent-children relationships](/guide/users/parent-children.html).
                  enum:
                    - shareholder
                    - employee
                    - leader
                specifiedUSPerson:
                  type: integer
                  description: |
                    Should be set to `1` for any citizen or resident of the United States, e.g. at least one of the following conditions is true: 
                    * `country` or `secondaryCountry` = US (the address or the secondary address is in the US)
                    * `nationality` or `nationalityOther` = US (the user has the US nationality)
                    * `birthCountry` = US (the user is born in the US)
            
                    When set to `1`, the user must have a US tax residence declared.
            
                    Should be set to `0` otherwise.
            
                    You may read more about who is considered a US Person in the [dedicated article](/guide/users/tax-residence.html).
                  enum: [0, 1]
                controllingPersonType:
                  type: integer
                  description: |
                    Type of relationship:
                    * `0` – None (default)
                    * `1` – Shareholder
                    * `2` – Other_relationship
                    * `3` – Director

                    You may read more about [parent-children relationships](/guide/users/parent-children.html).
                  enum: [0, 1, 2, 3]
                  default: 0
                employeeType:
                  type: integer
                  description: | 
                    The role of the user in [parent-children relationships](/guide/users/parent-children.html):
                    * `0` – None (default)
                    * `1` – Leader
                    * `2` – Employee
                  enum: [0, 1, 2]
                  default: 0
                entityType:
                  type: integer
                  deprecated: true
                  enum: [1, 2, 3, 4, 5]
                title:
                  type: string
                  description: |
                    The title of the user, which can be one of the following:
                    * `M` – Stands for mister (Mr.)
                    * `MME` – Stands for missus (Mrs.)
                    * `MLLE` – Stands for miss
                    * `MX` – Gender-neutral title
                  enum:
                    - M
                    - MME
                    - MLLE
                    - MX
                  example: "MX"
                firstname:
                  type: string
                  # pattern: "^[a-zA-ZÀ-ÖØ-öø-ÿœÆŒ\\s'-]+$"
                  minLength: 1
                  maxLength: 150
                  description: | 
                    The first name of the Physical User (`userTypeId` `1`).

                    Accepts ISO 8859-15 characters except: `!`, `"`, `#`, `$`, `%`, `&`, `(`, `)`, `*`, `+`, `/`, `<`, `=`, `>`, `?`, `@`, `[`, `\`, `]`, `_`, `{`, `|`, `}`, `~`, `¡`, `¢`, `£`, `€`, `¥`, `Š`, `§`, `š`, `©`, `ª`, `«`, `¬`, `®`, `¯`, `°`, `±`, `²`, `³`, `µ`, `¶`, `·`, `¹`, `º`, `»`, `¿`, `÷`.

                    A character cannot be repeated more than 3 times in a row.
                  example: "Alex"
                lastname:
                  type: string
                  # pattern: "^[a-zA-ZÀ-ÖØ-öø-ÿœÆŒ\\s'-]+$"
                  minLength: 1
                  maxLength: 150
                  description: |
                    The last name of the Physical User (`userTypeId` `1`).

                    Accepts ISO 8859-15 characters except: `!`, `"`, `#`, `$`, `%`, `&`, `(`, `)`, `*`, `+`, `/`, `<`, `=`, `>`, `?`, `@`, `[`, `\`, `]`, `_`, `{`, `|`, `}`, `~`, `¡`, `¢`, `£`, `€`, `¥`, `Š`, `§`, `š`, `©`, `ª`, `«`, `¬`, `®`, `¯`, `°`, `±`, `²`, `³`, `µ`, `¶`, `·`, `¹`, `º`, `»`, `¿`, `÷`.

                    A character cannot be repeated more than 3 times in a row.
                  example: "Oak"
                middleNames:
                  type: string
                  minLength: 1
                  maxLength: 150
                  description: |
                    The middle names of the Physical User (`userTypeId` `1`), if any. Several middle names must be separated by a comma.

                    Accepts ISO 8859-15 characters except: `!`, `"`, `#`, `$`, `%`, `&`, `(`, `)`, `*`, `+`, `/`, `<`, `=`, `>`, `?`, `@`, `[`, `\`, `]`, `_`, `{`, `|`, `}`, `~`, `¡`, `¢`, `£`, `€`, `¥`, `Š`, `§`, `š`, `©`, `ª`, `«`, `¬`, `®`, `¯`, `°`, `±`, `²`, `³`, `µ`, `¶`, `·`, `¹`, `º`, `»`, `¿`, `÷`.

                    A character cannot be repeated more than 3 times in a row.
                  example: "Chris"
                birthday:
                  type: string
                  format: date
                  description: | 
                    The birth date of the Physical User (`userTypeId` `1`). The user can't be more than a 100 years old upon reation.
                  example: "1990-10-29"
                email:
                  type: string
                  maxLength: 200
                  description: |
                    The email of the User. Must be valid and unique.

                    Please note only active users are checked for email uniqueness. `CANCELED` user emails can be reused to facilitate account re-creation.
                  example: "aoak@example.com"
                address1:
                  type: string
                  minLength: 3
                  maxLength: 150
                  oneOf:
                    - title: France (FR)
                      type: string
                      minLength: 3
                      maxLength: 150
                      # pattern: "^[a-zA-Z0-9À-ÖØ-öø-ÿœÆŒ\\s.,\\[\\]{}€@#\\-:( )/=' +?!\"%*;°_]+$"
                      description: |
                        The User postal address (main) for users whose `distributionCountry` is `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                        
                        **Characters:** Supports uppercase/lowercase letters with accents, digits, spaces, and the following symbols: `., [] {} € @ # - : ( ) / = ' + ? ! " % & * ; ° _`.
                      example: "14 Rue de la Paix"

                    - title: Other countries
                      type: string
                      minLength: 3
                      maxLength: 150
                      # pattern: "^[\\u0020-\\u007E\\u00A0-\\u00FF\\u0152\\u0153\\u0160\\u0161\\u0178\\u017D\\u017E\\u20AC]+$"
                      description: |
                        The User postal address (main) for users whose `distributionCountry` is other than `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                        
                        **Characters:** Full ISO 8859-15 standard character set.
                      example: "123 Main Street"
                address2:
                  type: string
                  minLength: 3
                  maxLength: 150
                  oneOf:
                    - title: France (FR)
                      type: string
                      minLength: 3
                      maxLength: 150
                      # pattern: "^[a-zA-Z0-9À-ÖØ-öø-ÿœÆŒ\\s.,\\[\\]{}€@#\\-:( )/=' +?!\"%*;°_]+$"
                      description: |
                        The User postal address (complement) for users whose `distributionCountry` is `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                        
                        **Characters:** Supports uppercase/lowercase letters with accents, digits, spaces, and the following symbols: `., [] {} € @ # - : ( ) / = ' + ? ! " % & * ; ° _`.
                    - title: Other countries
                      type: string
                      minLength: 3
                      maxLength: 150
                      # pattern: "^[\\u0020-\\u007E\\u00A0-\\u00FF\\u0152\\u0153\\u0160\\u0161\\u0178\\u017D\\u017E\\u20AC]+$"
                      description: |
                        The User postal address (complement) for users whose `distributionCountry` is other than `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                address3:
                  type: string
                  minLength: 3
                  maxLength: 150
                  oneOf:
                    - title: France (FR)
                      type: string
                      minLength: 3
                      maxLength: 150
                      # pattern: "^[a-zA-Z0-9À-ÖØ-öø-ÿœÆŒ\\s.,\\[\\]{}€@#\\-:( )/=' +?!\"%*;°_]+$"
                      description: |
                        The User postal address (complement2) for users whose `distributionCountry` is `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                        
                        **Characters:** Supports uppercase/lowercase letters with accents, digits, spaces, and the following symbols: `., [] {} € @ # - : ( ) / = ' + ? ! " % & * ; ° _`.
                    - title: Other countries
                      type: string
                      minLength: 3
                      maxLength: 150
                      # pattern: "^[\\u0020-\\u007E\\u00A0-\\u00FF\\u0152\\u0153\\u0160\\u0161\\u0178\\u017D\\u017E\\u20AC]+$"
                      description: |
                        The User postal address (complement2) for users whose `distributionCountry` is other than `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                        
                        **Characters:** Full ISO 8859-15 standard character set.
                postcode:
                  oneOf:
                    - title: European 5-Digit Format
                      type: string
                      # pattern: '^\d{5}$'
                      minLength: 5
                      maxLength: 5
                      description: The postal code of the address. Applicable for BE, DE, ES, FR, IT. Must always correspond with the provided city.
                      example: "75001"
                    - title: International Format
                      type: string
                      maxLength: 20
                      format: ISO 8859-15 subset
                      # pattern: "^[a-zA-Z0-9'\\-,. áàâäãåçéèêëíìîïñóòôöõúùûüýÿæœÁÀÂÄÃÅÇÉÈÊËÍÌÎÏÑÓÒÔÖÕÚÙÛÜÝŸÆŒ€]+$"
                      description: The postal code of the address. Applicable for all other countries. Must always correspond with the provided city.
                      example: "SW1A 1AA"
                city:
                  type: string
                  description: The User address city.
                state:
                  type: string
                  maxLength: 100
                  # pattern: "^[a-zA-ZÀ-ÖØ-öø-ÿœÆŒŠšŽžŸ\\s'-]+$"
                  description: |
                    The state of the user address.
                    
                    **Validation Rules:**
                    - **Characters:** Supports the ISO 8859-15 set, including standard letters, accented characters, spaces, hyphens, and apostrophes.
                    - **Anti-Spam:** A character cannot be repeated more than 3 times consecutively (e.g., "AAAA" is invalid).
                country:
                  type: string
                  description: The country of the user's address.
                  format: ISO 3166-1 alpha-2
                  example: "FR"
                distributionCountry:
                  type: string
                  nullable: true
                  description: | 
                    The country in which the end user is using your services. Available values may vary depending on your configuration, see [Distribution Country](/guide/users/introduction.html#distribution-country-distributioncountry) for more information.

                    This field is only required when you operate in multiple countries. Otherwise, it either defaults to your country or is set to `null`.
                  format: ISO 3166-1 alpha-2
                  example: "FR"
                  enum:
                    - FR
                    - ES
                    - IT
                    - DE
                    - BE
                    - NL
                secondaryAddress1:
                  type: string
                  minLength: 3
                  maxLength: 150
                  oneOf:
                    - title: France (FR)
                      type: string
                      minLength: 3
                      maxLength: 150
                      # pattern: "^[a-zA-Z0-9À-ÖØ-öø-ÿœÆŒ\\s.,\\[\\]{}€@#\\-:( )/=' +?!\"%*;°_]+$"
                      description: |
                        The User secondary postal address (main) for users whose `distributionCountry` is `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                        
                        **Characters:** Supports uppercase/lowercase letters with accents, digits, spaces, and the following symbols: `., [] {} € @ # - : ( ) / = ' + ? ! " % & * ; ° _`.
                      example: "14 Rue de la Paix, 2ème étage"
                    - title: Other countries
                      type: string
                      minLength: 3
                      maxLength: 150
                      # pattern: "^[\\u0020-\\u007E\\u00A0-\\u00FF\\u0152\\u0153\\u0160\\u0161\\u0178\\u017D\\u017E\\u20AC]+$"
                      description: |
                        The User secondary postal address (main) for users whose `distributionCountry` is other than `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                        
                        **Characters:** Full ISO 8859-15 standard character set.
                      example: "123 Main Street"
                secondaryAddress2:
                  type: string
                  minLength: 3
                  maxLength: 150
                  description: | 
                    The User secondary postal address (complement). Cannot contain carriage return and cannot have the same character more than 3 times in a row.

                    If the `distributionCountry` is `FR`, the following characters are accepted (uppercase or lowercase):
                    * The 26 letters of the Roman alphabet
                    * 16 letters with diacritical marks (À Â Ä Ç É È Ê Ë Î Ï Ô Ö Ù Û Ü Ÿ)
                    * 2 ligatures (æ, œ)
                    * Spaces, hyphens, apostrophes, or slashes « » /
                    * Numeric characters

                    If the `distributionCountry` is other than `FR`, the ISO 8859-15 standard applies.
                secondaryAddress3:
                  type: string
                  minLength: 3
                  maxLength: 150
                  description: | 
                    The User secondary postal address (complement2). Cannot contain carriage return and cannot have the same character more than 3 times in a row.

                    If the `distributionCountry` is `FR`, the following characters are accepted (uppercase or lowercase):
                    * The 26 letters of the Roman alphabet
                    * 16 letters with diacritical marks (À Â Ä Ç É È Ê Ë Î Ï Ô Ö Ù Û Ü Ÿ)
                    * 2 ligatures (æ, œ)
                    * Spaces, hyphens, apostrophes, or slashes « » /
                    * Numeric characters

                    If the `distributionCountry` is other than `FR`, the ISO 8859-15 standard applies.
                secondaryPostcode:
                  oneOf:
                    - title: European 5-Digit Format
                      type: string
                      # pattern: '^\d{5}$'
                      minLength: 5
                      maxLength: 5
                      description: The postal code of the address. Applicable for BE, DE, ES, FR, IT. Must always correspond with the provided city.
                      example: "75001"
                    - title: International Format
                      type: string
                      maxLength: 20
                      format: ISO 8859-15 subset
                      # pattern: "^[a-zA-Z0-9'\\-,. áàâäãåçéèêëíìîïñóòôöõúùûüýÿæœÁÀÂÄÃÅÇÉÈÊËÍÌÎÏÑÓÒÔÖÕÚÙÛÜÝŸÆŒ€]+$"
                      description: The postal code of the address. Applicable for all other countries. Must always correspond with the provided city.
                      example: "SW1A 1AA"
                secondaryCity:
                  type: string
                  description: The User secondary address city.
                secondaryState:
                  type: string
                  maxLength: 100
                  # pattern: "^[a-zA-ZÀ-ÖØ-öø-ÿœÆŒŠšŽžŸ\\s'-]+$"
                  description: |
                    The state of the user secondary address.
                    
                    **Validation Rules:**
                    - **Characters:** Supports the ISO 8859-15 set, including standard letters, accented characters, spaces, hyphens, and apostrophes.
                    - **Anti-Spam:** A character cannot be repeated more than 3 times consecutively (e.g., "AAAA" is invalid).
                secondaryCountry:
                  type: string
                  description: | 
                    The User secondary address country. 
                  format: ISO 3166-1 alpha-2
                  example: "FR"
                phone:
                  type: string
                  description: |
                    The phone number of the user in international **E.164 format**. 
                    It must start with a plus sign (`+`) followed by the country code and the national number.
                  # pattern: '^\+[1-9]\d{1,14}$'
                  example: "+33123456789"
                mobile:
                  type: string
                  description: |
                    The mobile phone number of the user in international **E.164 format**. 
                    It must start with a plus sign (`+`) followed by the country code and the national number.
                  # pattern: '^\+[1-9]\d{1,14}$'
                  example: "+33123456789"
                nationality:
                  type: string
                  description: | 
                    The User nationality.
                  format: ISO 3166-1 alpha-2
                  example: "FR"
                nationalityOther:
                  type: string
                  description: |
                    The User other nationality.
                  format: ISO 3166-1 alpha-2
                  example: "FR"
                placeOfBirth:
                  type: string
                  maxLength: 100
                  # pattern: "^[a-zA-Z0-9À-ÖØ-öø-ÿœÆŒ\\s'-]+$"
                  description: |
                    The city in which the Physical User was born.
                    
                    **Validation Rules:**
                    - **Geographic Accuracy:** Must be an existing city located within the provided `birthCountry`.
                    - **Characters:** Alphanumeric characters, spaces, hyphens, and apostrophes are allowed.
                    - **Forbidden:** Special symbols (e.g., `/`, `@`, `#`, `!`) and commas are prohibited.
                    - **ISO 8859-15:** Supports standard European accented characters and ligatures.
                  example: "Aix-en-Provence"
                birthCountry: 
                  type: string
                  description: The country in which the User was born.
                  format: ISO 3166-1 alpha-2
                  example: "FR"
                occupation:
                  type: string
                  minLength: 1
                  maxLength: 200
                  # pattern: "^[a-zA-ZÀ-ÖØ-öø-ÿœÆŒ\\s'-]+$"
                  description: |
                    Free field to specify the occupation of the Physical User (`userTypeId` `1`).

                    Accepts ISO 8859-15 characters except: `!`, `"`, `#`, `$`, `%`, `&`, `(`, `)`, `*`, `+`, `/`, `<`, `=`, `>`, `?`, `@`, `[`, `\`, `]`, `_`, `{`, `|`, `}`, `~`, `¡`, `¢`, `£`, `€`, `¥`, `Š`, `§`, `š`, `©`, `ª`, `«`, `¬`, `®`, `¯`, `°`, `±`, `²`, `³`, `µ`, `¶`, `·`, `¹`, `º`, `»`, `¿`, `÷`.

                    A character cannot be repeated more than 3 times in a row.
                incomeRange:
                  type: string
                  deprecated: true
                  description: Deprecated. Use `monthlyIncomeRange` instead.
                  enum:
                    - 0-18
                    - 19-23
                    - 24-27
                    - 28-35
                    - 36-56
                    - 57-*
                legalName:
                  oneOf:
                    - title: French SIREN Format
                      type: string
                      minLength: 1
                      maxLength: 100
                      # pattern: "^[a-zA-Z0-9ÀÂÄÇÉÈÊËÎÏÔÖÙÛÜŸàâäçéèêëîïôöùûüÿæœÆŒ .,\\[\\]{}€@#\\-:( )/=' +?!\"%&*;<>=°_]+$"
                      description: |
                        The official name of the legal entity (or self-employed user) as registered with national authorities. Compliant with the French SIREN naming standards; must follow the SIREN referential (supports specific accents, ligatures like 'œ', and symbols).

                        If you're issuing cards, please not this value automatically populates the `embossedLegalName` field which has a max. length of 20 characters.
                    - title: European Standard Format
                      type: string
                      format: ISO 8859-15
                      minLength: 1
                      maxLength: 100
                      # pattern: "^[\\u0020-\\u007E\\u00A0-\\u00FF\\u0152\\u0153\\u0160\\u0161\\u0178\\u017D\\u017E\\u20AC]+$"
                      description: | 
                        The official name of the legal entity (or self-employed user) as registered with national authorities. Standard ISO 8859-15 characters for ES, IT, DE, BE, NL.

                        If you're issuing cards, please not this value automatically populates the `embossedLegalName` field which has a max. length of 20 characters.
                legalRegistrationNumber:
                  oneOf:
                    - title: France (SIREN/SIRET)
                      type: string
                      # pattern: '^\d{9,14}$'
                      description: |
                        The official registration number of the legal entity. 
                        Mandatory for FR. Numeric characters only (9 or 14 digits).
                        If provided, the `country` field must be present as well.
                      example: "12345678901234"
                    - title: Spain (NIF)
                      type: string
                      # pattern: '^[A-Z]\d{7}[A-Z0-9]$'
                      description: |
                        The official registration number of the legal entity. 
                        Mandatory for ES. Structure: 1 letter + 7 digits + 1 control character (letter or digit).
                        If provided, the `country` field must be present as well.
                      example: "A1234567B"
                    - title: Italy (Numero REA)
                      type: string
                      # pattern: '^[A-Z]{2}\d+$'
                      description: |
                        The official registration number of the legal entity.
                        Mandatory for IT. Structure: 2-letter Provincial Code + digits.
                        If provided, the `country` field must be present as well.
                      example: "RM123456"
                    - title: Germany & Global (Alphanumeric)
                      type: string
                      # pattern: '^[a-zA-Z0-9]+$'
                      description: |
                        The official registration number of the legal entity. 
                        Optional for DE. Alphanumeric for all other countries.
                        If provided, the `country` field must be present as well.
                      example: "HRB12345"
                legalTvaNumber:
                  type: string
                  minLength: 3
                  maxLength: 20
                  description: |
                    The VAT number of the legal entity.
                    
                    This field is referred to as **Codice fiscale** in Italy and **Umsatzsteuer-ID** in Germany.
                    
                    **KYB Requirements:**
                    - **Mandatory:** For Italy (IT) and Spain (ES).
                    - **Optional:** For France (FR) and Germany (DE).
                  # pattern: '^[a-zA-Z0-9]{3,20}$'
                  example: "IT12345678901"
                legalRegistrationDate:
                  type: string
                  format: date
                  description: | 
                    The date on which the legal entity was officially registered with the relevant national authorities. Must be in the past.
                  example: "2020-01-21"
                legalForm:
                  type: string
                  description: |
                    The legal form/category of the company. See the [Legal Forms](/guide/users/introduction.html#legal-forms-legalform) section for more information.
                legalShareCapital:
                  type: integer
                  description: The Business share capital.
                legalSector:
                  type: string
                  description: |
                    The Business Sector of the company (NAF or NACE code in France). The expected format depends on `legalSectorType`

                    If the value is one of the following, the `userTypeId` must be `3`: `9411Z`, `9412Z`, `9420Z`, `9491Z`, `9492Z`, `9499Z`.
                    
                    You may check out [the authoritative list](https://www.insee.fr/fr/information/2120875)
                legalAnnualTurnOver:
                  type: string
                  description: The Business annual turnover (in k€).
                  enum:
                    - 0-39
                    - 40-99
                    - 100-249
                    - 250-999
                    - 1000-2999
                    - 3000-9999
                    - 10000-99999
                    - 100000-*
                legalNetIncomeRange:
                  type: string
                  description: The Business net income range (in k€). Negative values are only accepted for legal entities.
                  enum:
                    - '*--500'
                    - '-499--150'
                    - '-149--50'
                    - '-49--10'
                    - '-9--1'
                    - 0-4
                    - 5-9
                    - 10-49
                    - 50-149
                    - 150-499
                    - 500-*
                legalNumberOfEmployeeRange:
                  type: string
                  description: The number of employees of the legal entity.
                  enum:
                    - '0'
                    - 1-9
                    - 10-99
                    - 100-249
                    - 250-*
                effectiveBeneficiary:
                  type: integer
                  description: The effective beneficiary shares of the legal entity (e.g., for a beneficiary holding 70% of a company, value must be `70`). For shareholders only.
                language: 
                  type: string
                  description: |
                    The preferred language of the User. 
                  format: ISO 639-1
                  example: "fr"
                taxNumber:
                  type: string
                  deprecated: true
                  description: Deprecated. You must use the `taxResidence` endpoint.
                taxResidence:
                  type: string
                  deprecated: true
                  description: Deprecated. You must use the `taxResidence` endpoint.
                position:
                  type: string
                  description: The geographic activity coverage (for NGOs only).
                personalAssets:
                  type: string
                  description: Deprecated. You must use `personalAssetsRange` instead.
                  deprecated: true
                  enum:
                    - 0-2
                    - 3-22
                    - 23-128
                    - 129-319
                    - 320-464
                    - 465-
                activityOutsideEu:
                  type: integer
                  description: |
                    For Users obligated to complete a due diligence questionnaire regarding sanctions and embargoes. 

                    Whether the entity and its business units, subsidiaries, and joint ventures have a commercial activity outside of the European Union.

                    Can be:
                    * `0` – False
                    * `1` – True. When set to this value, the next attributes become mandatory. 

                    See the [Sanctions and embargo](/guide/users/legal-entity.html#sanctions-and-embargo) article for more information.
                  enum: [0, 1]
                economicSanctions:
                  type: integer
                  description: |
                    For Users obligated to complete a due diligence questionnaire regarding sanctions and embargoes, and for which the `activityOutsideEu` value is set to `1`.

                    Whether the entity, its subsidiaries, entities, employees, directors, beneficial owners, or joint ventures are subject to Economic Sanctions.

                    Can be:
                    * `0` – False
                    * `1` – True 

                    See the [Sanctions and embargo](/guide/users/legal-entity.html#sanctions-and-embargo) article for more information.
                  enum: [0, 1]
                residentCountriesSanctions:
                  type: integer
                  description: |
                    For Users obligated to complete a due diligence questionnaire regarding sanctions and embargoes, and for which the `activityOutsideEu` value is set to `1`.

                    Whether the entity, its subsidiaries, or joint ventures, located within or operating from any countries or territories are subject to Comprehensive Sanctions. 

                    Can be:
                    * `0` – False
                    * `1` – True 

                    See the [Sanctions and embargo](/guide/users/legal-entity.html#sanctions-and-embargo) article for more information.
                  enum: [0, 1]
                involvedSanctions:
                  type: integer
                  description: |
                    For Users obligated to complete a due diligence questionnaire regarding sanctions and embargoes, and for which the `activityOutsideEu` value is set to `1`.

                    Whether the entity, its subsidiaries, or joint ventures, are engaged in transactions, investments, business, or other dealings that directly or indirectly involve or benefit:
                    * Any countries or territories subject to Comprehensive Sanctions (Cuba, Iran, North Korea, Syria, Crimea, Ukrainian Oblasts not controlled by the government, or Russia), or 
                    * Any person or entity which is the target of any Sanctions (“Sanctioned Targets”).

                    Can be:
                    * `0` – False
                    * `1` – True 

                    See the [Sanctions and embargo](/guide/users/legal-entity.html#sanctions-and-embargo) article for more information.
                  enum: [0, 1]
                entitySanctionsQuestionnaire:
                  type: integer
                  description: |
                    For Users obligated to complete a due diligence questionnaire regarding sanctions and embargoes, and for which the `activityOutsideEu` value is set to `1`.

                    Defines the scope to which the `activityOutsideEu` field applies:
                    * `0` – Not applicable
                    * `1` – Only the legal entity
                    * `2` – The legal entity and all its subsidiaries held at 100%
                    * `3` – The legal entity and all its subsidiaries held at 50% or more
                    * `4` – The legal entity and a list of subsidiaries

                    See the [Sanctions and embargo](/guide/users/legal-entity.html#sanctions-and-embargo) article for more information.

                  enum: [0, 1, 2, 3, 4]
                timezone:
                  type: string
                  description: |
                    The User timezone in the [tz database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) format.
                    The timezones have unique names in the form "Area/Location".

                    It may be used to enforce a card `paymentDailyLimit` based on the cardholder's timezone.
                  example: "Paris/France"
                occupationType:
                  type: string
                  description: Deprecated. Use `occupationCategory` instead.
                  deprecated: True
                  enum:
                    - self_employed
                    - public_sector_employees
                    - private_sector_employees
                    - retired_people_and_students
                    - without_any_professional_activity
                sourceOfFunds:
                  type: string
                  description: The source of funds for opening an account for a company or self-employed person.
                  enum: 
                    - donation
                    - inheritance
                    - loan 
                    - lottery
                    - pension
                    - proceeds_from_investment
                    - proceeds_from_sale
                    - salary
                    - saving
                legalSectorType:
                  type: string
                  description: |
                    Qualify the type of data in the `legalSector` field:
                    * If it is set to NACE the legalSector needs to be in a NACE format (4 digits). 
                    * If it is set to NAF (or not set at all) the legalSector needs to be in a NAF format (4 digits followed by a capital letter).
                  enum:
                    - NAF
                    - NACE
                isOnStockExchange:
                  type: integer
                  description: |
                    The user is a corporation and is quoted on an organized stock exchange.
                    * `0` – No
                    * `1` – Yes
                  enum: [0, 1]
                webauthn:
                  type: string
                  description: |
                    The `PublicKeyCredential` after the WebAuthn Register, encoded in base64.

                    See the [Web Native enrollment](/guide/strong-customer-authentication/user-enrollment.html#web-native-enrollment) article for more information.
                passcode:
                  type: string
                  description: |
                    Required if the `webauthn` field is provided without [user verification](/guide/strong-customer-authentication/user-enrollment.html#user-authentication-methods). Must be base64 encoded and encrypted. Initial passcode must at least 6 characters.

                    See the [Web Native enrollment](/guide/strong-customer-authentication/user-enrollment.html#web-native-enrollment) article for more information.
                occupationCategory:
                  type: integer
                  nullable: true
                  description: |
                    Type of occupation of the user. See [Occupation Category](/guide/users/physical.html#occupation-category-occupationcategory) for the list of values.
                  enum: [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]
                personalAssetsRange:
                  type: integer
                  nullable: true
                  description: |
                    The personal assets range of the user. See [Personal Assets Range](/guide/users/physical.html#personal-assets-range-personalassetsrange) for the list of values.
                  enum: [0,1,2,3,4,5,6,7]
                monthlyIncomeRange:
                  nullable: true
                  type: integer
                  description: |
                    Net monthly income of the user. See [Monthly Income Range](/guide/users/physical.html#monthly-income-range-monthlyincomerange) for the list of values.
                  enum: [1,2,3,4,5,6,7]
                scaWalletTag:
                  type: string
                  maxLength: 256
                  description: |
                    Custom value for the SCA Wallet [when enrolling a new user](/guide/strong-customer-authentication/user-enrollment.html#new-user-enrollment). Can be used to name the device for which the new SCA Wallet is created. 
                  example: "iPhone16"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - legal
          - admin
  /v1/users/{userId}:
    get:
      tags:
        - Users
      summary: Get User
      description: |
        Retrieve information about a user based on the `id`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getUser
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: userId
          in: path
          description: The unique identifier of the User.
          required: true
          schema:
            type: integer
            example: 12345
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: _embed
          in: query
          description: |
            Embeds related [User Relationships](/guide/users/relationships.html) data directly in the response. 
            
            Accepts a comma-separated list of values. When used, the User object in the response includes an `embed` object containing the requested relationship data.

            The embedded relationships are limited to 10 items per direction. Use `has_more` in the response to determine if additional relationships exist.
          schema:
            type: string
            enum:
              - ascending_relationships
              - descending_relationships
              - relationships
          example: "ascending_relationships,descending_relationships"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    put:
      tags:
        - Users
      summary: Update User
      description: | 
        Update information regarding the User.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-operation |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`user.update`](/guide/users/events.html#user-update) |
      operationId: putUser
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: userId
          in: path
          description: The unique identifier of the User.
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                userTag:
                  type: string
                  maxLength: 250
                  description: |
                    Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
                    
                    Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                specifiedUSPerson:
                  type: integer
                  description: | 
                    You may read more about who is considered a US Person in the [dedicated article](/guide/users/tax-residence.html).
                controllingPersonType:
                  type: integer
                  description: |
                    Type of relationship, among the following:
                    * `0` – None (default)
                    * `1` – Shareholder
                    * `2` – Other_relationship
                    * `3` – Director
                  enum: [0,1,2,3]
                  default: 0
                employeeType:
                  type: integer
                  description: |
                    The type of relationship among the following:
                    * `0` – None (default)
                    * `1` – Leader
                    * `2` – Employee
                  enum: [0,1,2]
                  default: 0
                title:
                  type: string
                  description: |
                    The title of the user, which can be one of the following:
                    * `M` – Stands for mister (Mr.)
                    * `MME` – Stands for missus (Mrs.)
                    * `MLLE` – Stands for miss
                    * `MX` – Gender-neutral title
                  enum: 
                    - M
                    - MME
                    - MLLE
                    - MX
                firstname:
                  type: string
                  minLength: 1
                  maxLength: 150
                  description: | 
                    The first name of the Physical User (`userTypeId` `1`).

                    Accepts ISO 8859-15 characters except: `!`, `"`, `#`, `$`, `%`, `&`, `(`, `)`, `*`, `+`, `/`, `<`, `=`, `>`, `?`, `@`, `[`, `\`, `]`, `_`, `{`, `|`, `}`, `~`, `¡`, `¢`, `£`, `€`, `¥`, `Š`, `§`, `š`, `©`, `ª`, `«`, `¬`, `®`, `¯`, `°`, `±`, `²`, `³`, `µ`, `¶`, `·`, `¹`, `º`, `»`, `¿`, `÷`.

                    A character cannot be repeated more than 3 times in a row.
                lastname:
                  type: string
                  minLength: 1
                  maxLength: 150
                  description: |
                    The last name of the Physical User (`userTypeId` `1`).

                    Accepts ISO 8859-15 characters except: `!`, `"`, `#`, `$`, `%`, `&`, `(`, `)`, `*`, `+`, `/`, `<`, `=`, `>`, `?`, `@`, `[`, `\`, `]`, `_`, `{`, `|`, `}`, `~`, `¡`, `¢`, `£`, `€`, `¥`, `Š`, `§`, `š`, `©`, `ª`, `«`, `¬`, `®`, `¯`, `°`, `±`, `²`, `³`, `µ`, `¶`, `·`, `¹`, `º`, `»`, `¿`, `÷`.

                    A character cannot be repeated more than 3 times in a row.
                middleNames:
                  type: string
                  minLength: 1
                  maxLength: 150
                  description: |
                    The middle names of the Physical User (`userTypeId` `1`), if any. Several middle names must be separated by a comma.

                    Accepts ISO 8859-15 characters except: `!`, `"`, `#`, `$`, `%`, `&`, `(`, `)`, `*`, `+`, `/`, `<`, `=`, `>`, `?`, `@`, `[`, `\`, `]`, `_`, `{`, `|`, `}`, `~`, `¡`, `¢`, `£`, `€`, `¥`, `Š`, `§`, `š`, `©`, `ª`, `«`, `¬`, `®`, `¯`, `°`, `±`, `²`, `³`, `µ`, `¶`, `·`, `¹`, `º`, `»`, `¿`, `÷`.

                    A character cannot be repeated more than 3 times in a row.
                birthday:
                  type: string
                  format: date
                  description: | 
                    The birth date of the Physical User (`userTypeId` `1`). The user can't be more than a 100 years old upon reation.
                  example: "1990-10-29"
                email:
                  type: string
                  maxLength: 200
                  description: |
                    The email of the User. Must be valid and unique.

                    Please note only active users are checked for email uniqueness. `CANCELED` user emails can be reused to facilitate account re-creation.
                address1:
                  type: string
                  minLength: 3
                  maxLength: 150
                  oneOf:
                    - title: France (FR)
                      type: string
                      minLength: 3
                      maxLength: 150
                      # pattern: "^[a-zA-Z0-9À-ÖØ-öø-ÿœÆŒ\\s.,\\[\\]{}€@#\\-:( )/=' +?!\"%*;°_]+$"
                      description: |
                        The User postal address (main) for users whose `distributionCountry` is `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                        
                        **Characters:** Supports uppercase/lowercase letters with accents, digits, spaces, and the following symbols: `., [] {} € @ # - : ( ) / = ' + ? ! " % & * ; ° _`.
                      example: "14 Rue de la Paix"
                    - title: Other countries
                      type: string
                      minLength: 3
                      maxLength: 150
                      # pattern: "^[\\u0020-\\u007E\\u00A0-\\u00FF\\u0152\\u0153\\u0160\\u0161\\u0178\\u017D\\u017E\\u20AC]+$"
                      description: |
                        The User postal address (main) for users whose `distributionCountry` is other than `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                        
                        **Characters:** Full ISO 8859-15 standard character set.
                      example: "123 Main Street"
                address2:
                  type: string
                  minLength: 3
                  maxLength: 150
                  oneOf:
                    - title: France (FR)
                      type: string
                      minLength: 3
                      maxLength: 150
                      # pattern: "^[a-zA-Z0-9À-ÖØ-öø-ÿœÆŒ\\s.,\\[\\]{}€@#\\-:( )/=' +?!\"%*;°_]+$"
                      description: |
                        The User postal address (complement) for users whose `distributionCountry` is `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                        
                        **Characters:** Supports uppercase/lowercase letters with accents, digits, spaces, and the following symbols: `., [] {} € @ # - : ( ) / = ' + ? ! " % & * ; ° _`.
                    - title: Other countries
                      type: string
                      minLength: 3
                      maxLength: 150
                      # pattern: "^[\\u0020-\\u007E\\u00A0-\\u00FF\\u0152\\u0153\\u0160\\u0161\\u0178\\u017D\\u017E\\u20AC]+$"
                      description: |
                        The User postal address (complement) for users whose `distributionCountry` is other than `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                        
                        **Characters:** Full ISO 8859-15 standard character set.
                address3:
                  type: string
                  minLength: 3
                  maxLength: 150
                  oneOf:
                    - title: France (FR)
                      type: string
                      minLength: 3
                      maxLength: 150
                      # pattern: "^[a-zA-Z0-9À-ÖØ-öø-ÿœÆŒ\\s.,\\[\\]{}€@#\\-:( )/=' +?!\"%*;°_]+$"
                      description: |
                        The User postal address (complement2) for users whose `distributionCountry` is `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                        
                        **Characters:** Supports uppercase/lowercase letters with accents, digits, spaces, and the following symbols: `., [] {} € @ # - : ( ) / = ' + ? ! " % & * ; ° _`.
                    - title: Other countries
                      type: string
                      minLength: 3
                      maxLength: 150
                      # pattern: "^[\\u0020-\\u007E\\u00A0-\\u00FF\\u0152\\u0153\\u0160\\u0161\\u0178\\u017D\\u017E\\u20AC]+$"
                      description: |
                        The User postal address (complement2) for users whose `distributionCountry` is other than `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                        
                        **Characters:** Full ISO 8859-15 standard character set.
                postcode:
                  oneOf:
                    - title: European 5-Digit Format
                      type: string
                      # pattern: '^\d{5}$'
                      minLength: 5
                      maxLength: 5
                      description: The postal code of the address. Applicable for BE, DE, ES, FR, IT. Must always correspond with the provided city.
                      example: "75001"
                    - title: International Format
                      type: string
                      maxLength: 20
                      format: ISO 8859-15 subset
                      # pattern: "^[a-zA-Z0-9'\\-,. áàâäãåçéèêëíìîïñóòôöõúùûüýÿæœÁÀÂÄÃÅÇÉÈÊËÍÌÎÏÑÓÒÔÖÕÚÙÛÜÝŸÆŒ€]+$"
                      description: The postal code of the address. Applicable for all other countries. Must always correspond with the provided city.
                      example: "SW1A 1AA"
                city:
                  type: string
                  description: The User address city.
                state:
                  type: string
                  maxLength: 100
                  # pattern: "^[a-zA-ZÀ-ÖØ-öø-ÿœÆŒŠšŽžŸ\\s'-]+$"
                  description: |
                    The state of the user address.
                    
                    **Validation Rules:**
                    - **Characters:** Supports the ISO 8859-15 set, including standard letters, accented characters, spaces, hyphens, and apostrophes.
                    - **Anti-Spam:** A character cannot be repeated more than 3 times consecutively (e.g., "AAAA" is invalid).
                country:
                  type: string
                  description: The country of the user's address.
                  format: ISO 3166-1 alpha-2
                distributionCountry:
                  type: string
                  nullable: true
                  description: | 
                    The country in which the end user is using your services. Available values may vary depending on your configuration, see [Distribution Country](/guide/users/introduction.html#distribution-country-distributioncountry) for more information.
                    
                    This field is only required when you operate in multiple countries. Otherwise, it either defaults to your country or is set to `null`.
                  format: ISO 3166-1 alpha-2
                  example: "FR"
                  enum:
                    - FR
                    - ES
                    - IT
                    - DE
                    - BE
                    - NL
                secondaryAddress1:
                  type: string
                  minLength: 3
                  maxLength: 150
                  oneOf:
                    - title: France (FR)
                      type: string
                      minLength: 3
                      maxLength: 150
                      # pattern: "^[a-zA-Z0-9À-ÖØ-öø-ÿœÆŒ\\s.,\\[\\]{}€@#\\-:( )/=' +?!\"%*;°_]+$"
                      description: |
                        The User secondary postal address (main) for users whose `distributionCountry` is `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                        
                        **Characters:** Supports uppercase/lowercase letters with accents, digits, spaces, and the following symbols: `., [] {} € @ # - : ( ) / = ' + ? ! " % & * ; ° _`.
                      example: "14 Rue de la Paix"
                    - title: Other countries
                      type: string
                      minLength: 3
                      maxLength: 150
                      # pattern: "^[\\u0020-\\u007E\\u00A0-\\u00FF\\u0152\\u0153\\u0160\\u0161\\u0178\\u017D\\u017E\\u20AC]+$"
                      description: |
                        The User secondary postal address (main) for users whose `distributionCountry` is other than `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                        
                        **Characters:** Full ISO 8859-15 standard character set.
                      example: "123 Main Street"
                secondaryAddress2:
                  type: string
                  minLength: 3
                  maxLength: 150
                  oneOf:
                    - title: France (FR)
                      type: string
                      minLength: 3
                      maxLength: 150
                      # pattern: "^[a-zA-Z0-9À-ÖØ-öø-ÿœÆŒ\\s.,\\[\\]{}€@#\\-:( )/=' +?!\"%*;°_]+$"
                      description: |
                        The User secondary postal address (complement) for users whose `distributionCountry` is `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                        
                        **Characters:** Supports uppercase/lowercase letters with accents, digits, spaces, and the following symbols: `., [] {} € @ # - : ( ) / = ' + ? ! " % & * ; ° _`.
                    - title: Other countries
                      type: string
                      minLength: 3
                      maxLength: 150
                      # pattern: "^[\\u0020-\\u007E\\u00A0-\\u00FF\\u0152\\u0153\\u0160\\u0161\\u0178\\u017D\\u017E\\u20AC]+$"
                      description: |
                        The User secondary postal address (complement) for users whose `distributionCountry` is other than `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                        
                        **Characters:** Full ISO 8859-15 standard character set.
                secondaryAddress3:
                  type: string
                  minLength: 3
                  maxLength: 150
                  oneOf:
                    - title: France (FR)
                      type: string
                      minLength: 3
                      maxLength: 150
                      # pattern: "^[a-zA-Z0-9À-ÖØ-öø-ÿœÆŒ\\s.,\\[\\]{}€@#\\-:( )/=' +?!\"%*;°_]+$"
                      description: |
                        The User secondary postal address (complement2) for users whose `distributionCountry` is `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                        
                        **Characters:** Supports uppercase/lowercase letters with accents, digits, spaces, and the following symbols: `., [] {} € @ # - : ( ) / = ' + ? ! " % & * ; ° _`.
                    - title: Other countries
                      type: string
                      minLength: 3
                      maxLength: 150
                      # pattern: "^[\\u0020-\\u007E\\u00A0-\\u00FF\\u0152\\u0153\\u0160\\u0161\\u0178\\u017D\\u017E\\u20AC]+$"
                      description: |
                        The User secondary postal address (complement2) for users whose `distributionCountry` is other than `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                        
                        **Characters:** Full ISO 8859-15 standard character set.
                secondaryPostcode:
                  oneOf:
                    - title: European 5-Digit Format
                      type: string
                      # pattern: '^\d{5}$'
                      minLength: 5
                      maxLength: 5
                      description: The postal code of the address. Applicable for BE, DE, ES, FR, IT. Must always correspond with the provided city.
                      example: "75001"
                    - title: International Format
                      type: string
                      maxLength: 20
                      format: ISO 8859-15 subset
                      # pattern: "^[a-zA-Z0-9'\\-,. áàâäãåçéèêëíìîïñóòôöõúùûüýÿæœÁÀÂÄÃÅÇÉÈÊËÍÌÎÏÑÓÒÔÖÕÚÙÛÜÝŸÆŒ€]+$"
                      description: The postal code of the address. Applicable for all other countries. Must always correspond with the provided city.
                      example: "SW1A 1AA"
                secondaryCity:
                  type: string
                  description: The User secondary address city.
                secondaryState:
                  type: string
                  maxLength: 100
                  # pattern: "^[a-zA-ZÀ-ÖØ-öø-ÿœÆŒŠšŽžŸ\\s'-]+$"
                  description: |
                    The state of the user secondary address.
                    
                    **Validation Rules:**
                    - **Characters:** Supports the ISO 8859-15 set, including standard letters, accented characters, spaces, hyphens, and apostrophes.
                    - **Anti-Spam:** A character cannot be repeated more than 3 times consecutively (e.g., "AAAA" is invalid).
                secondaryCountry:
                  type: string
                  format: ISO 3166-1 alpha-2
                  description: | 
                    The User secondary address country.
                phone:
                  type: string
                  description: |
                    The phone number of the user in international **E.164 format**. 
                    It must start with a plus sign (`+`) followed by the country code and the national number.
                  # pattern: '^\+[1-9]\d{1,14}$'
                  example: "+33123456789"
                mobile:
                  type: string
                  description: |
                    The mobile phone number of the user in international **E.164 format**. 
                    It must start with a plus sign (`+`) followed by the country code and the national number.
                  # pattern: '^\+[1-9]\d{1,14}$'
                  example: "+33123456789"
                nationality:
                  type: string
                  description: | 
                    The User nationality.
                  format: ISO 3166-1 alpha-2
                  example: "FR"
                nationalityOther:
                  type: string
                  description: |
                    The User other nationality.
                  format: ISO 3166-1 alpha-2
                  example: "FR"
                placeOfBirth:
                  type: string
                  maxLength: 100
                  # pattern: "^[a-zA-Z0-9À-ÖØ-öø-ÿœÆŒ\\s'-]+$"
                  description: |
                    The city in which the Physical User was born.
                    
                    **Validation Rules:**
                    - **Geographic Accuracy:** Must be an existing city located within the provided `birthCountry`.
                    - **Characters:** Alphanumeric characters, spaces, hyphens, and apostrophes are allowed.
                    - **Forbidden:** Special symbols (e.g., `/`, `@`, `#`, `!`) and commas are prohibited.
                    - **ISO 8859-15:** Supports standard European accented characters and ligatures.
                  example: "Aix-en-Provence"
                birthCountry: 
                  type: string
                  description: |
                    The User country of Birth. 
                  format: ISO 3166-1 alpha-2
                  example: "FR"
                occupation:
                  type: string
                  minLength: 1
                  maxLength: 200
                  # pattern: "^[a-zA-ZÀ-ÖØ-öø-ÿœÆŒ\\s'-]+$"
                  description: |
                    Free field to specify the occupation of the Physical User (`userTypeId` `1`).

                    Accepts ISO 8859-15 characters except: `!`, `"`, `#`, `$`, `%`, `&`, `(`, `)`, `*`, `+`, `/`, `<`, `=`, `>`, `?`, `@`, `[`, `\`, `]`, `_`, `{`, `|`, `}`, `~`, `¡`, `¢`, `£`, `€`, `¥`, `Š`, `§`, `š`, `©`, `ª`, `«`, `¬`, `®`, `¯`, `°`, `±`, `²`, `³`, `µ`, `¶`, `·`, `¹`, `º`, `»`, `¿`, `÷`.

                    A character cannot be repeated more than 3 times in a row.
                incomeRange:
                  type: string
                  description: The User income range.
                  enum:
                    - 0-18
                    - 19-23
                    - 24-27
                    - 28-35
                    - 36-56
                    - 57-*
                legalName:
                  oneOf:
                    - title: French SIREN Format
                      type: string
                      minLength: 1
                      maxLength: 100
                      # pattern: "^[a-zA-Z0-9ÀÂÄÇÉÈÊËÎÏÔÖÙÛÜŸàâäçéèêëîïôöùûüÿæœÆŒ .,\\[\\]{}€@#\\-:( )/=' +?!\"%&*;<>=°_]+$"
                      description: |
                        The official name of the legal entity (or self-employed user) as registered with national authorities. Compliant with the French SIREN naming standards; must follow the SIREN referential (supports specific accents, ligatures like 'œ', and symbols).

                        If you're issuing cards, please not this value automatically populates the `embossedLegalName` field which has a max. length of 20 characters.
                    - title: European Standard Format
                      type: string
                      format: ISO 8859-15
                      minLength: 1
                      maxLength: 100
                      # attern: "^[\\u0020-\\u007E\\u00A0-\\u00FF\\u0152\\u0153\\u0160\\u0161\\u0178\\u017D\\u017E\\u20AC]+$"
                      description: | 
                        The official name of the legal entity (or self-employed user) as registered with national authorities. Standard ISO 8859-15 characters for ES, IT, DE, BE, NL.

                        If you're issuing cards, please not this value automatically populates the `embossedLegalName` field which has a max. length of 20 characters.
                legalRegistrationNumber:
                  oneOf:
                    - title: France (SIREN/SIRET)
                      type: string
                      # pattern: '^\d{9,14}$'
                      description: |
                        The official registration number of the legal entity. 
                        Mandatory for FR. Numeric characters only (9 or 14 digits).
                        If provided, the `country` field must be present as well.
                      example: "12345678901234"
                    - title: Spain (NIF)
                      type: string
                      # pattern: '^[A-Z]\d{7}[A-Z0-9]$'
                      description: |
                        The official registration number of the legal entity. 
                        Mandatory for ES. Structure: 1 letter + 7 digits + 1 control character (letter or digit).
                        If provided, the `country` field must be present as well.
                      example: "A1234567B"
                    - title: Italy (Numero REA)
                      type: string
                      # pattern: '^[A-Z]{2}\d+$'
                      description: |
                        The official registration number of the legal entity.
                        Mandatory for IT. Structure: 2-letter Provincial Code + digits.
                        If provided, the `country` field must be present as well.
                      example: "RM123456"
                    - title: Germany & Global (Alphanumeric)
                      type: string
                      # pattern: '^[a-zA-Z0-9]+$'
                      description: |
                        The official registration number of the legal entity. 
                        Optional for DE. Alphanumeric for all other countries.
                        If provided, the `country` field must be present as well.
                      example: "HRB12345"
                legalTvaNumber:
                  type: string
                  minLength: 3
                  maxLength: 20
                  description: |
                    The VAT number of the legal entity.
                    
                    This field is referred to as **Codice fiscale** in Italy and **Umsatzsteuer-ID** in Germany.
                    
                    **KYB Requirements:**
                    - **Mandatory:** For Italy (IT) and Spain (ES).
                    - **Optional:** For France (FR) and Germany (DE).
                  # pattern: '^[a-zA-Z0-9]{3,20}$'
                  example: "IT12345678901"
                legalRegistrationDate:
                  type: string
                  format: date
                  description: | 
                    The date on which the legal entity was officially registered with the relevant national authorities. Must be in the past.
                  example: "2020-01-21"
                legalForm:
                  type: string
                  description: |
                   The legal form/category of the company. See the [Legal Forms](/guide/users/introduction.html#legal-forms-legalform) section for more information.
                legalShareCapital:
                  type: integer
                  description: The Business share capital.
                legalSector:
                  type: string
                  description: |
                    The Business Sector of the company (NAF or NACE code in France). The expected format depends on `legalSectorType`
                    
                    You may check out [the authoritative list](https://www.insee.fr/fr/information/2120875)
                legalAnnualTurnOver:
                  type: string
                  description: The Business annual turnover (in k€).
                  enum:
                    - 0-39
                    - 40-99
                    - 100-249
                    - 250-999
                    - 1000-2999
                    - 3000-9999
                    - 10000-99999
                    - 100000-*
                legalNetIncomeRange:
                  type: string
                  description: The Business net income range (in k€). Negative values are only accepted for legal entities.
                  enum:
                    - '*--500'
                    - '-499--150'
                    - '-149--50'
                    - '-49--10'
                    - '-9--1'
                    - 0-4
                    - 5-9
                    - 10-49
                    - 50-149
                    - 150-499
                    - 500-*
                legalNumberOfEmployeeRange:
                  type: string
                  description: The Business number of employees.
                  enum:
                    - '0'
                    - 1-9
                    - 10-99
                    - 100-249
                    - 250-*
                effectiveBeneficiary:
                  type: integer
                  description:  The effective beneficiary shares of the legal entity (e.g., for a beneficiary holding 70% of a company, value must be `70`). For shareholders only.
                language: 
                  type: string
                  description: |
                    The User preferred language. Format: ISO 639-1
                taxNumber:
                  type: string
                  deprecated: true
                  description: Deprecated. Your must use the `taxResidence` endpoint.
                taxResidence:
                  type: string
                  deprecated: true
                  description: Deprecated. Your must use the `taxResidence` endpoint.
                position:
                  type: string
                  description: The geographic activity coverage (for NGOs only).
                personalAssets:
                  type: string
                  description: Deprecated. You must use `personalAssetsRange` instead.
                  deprecated: true
                  enum:
                    - 0-2
                    - 3-22
                    - 23-128
                    - 129-319
                    - 320-464
                    - 465-
                activityOutsideEu:
                  type: integer
                  description: |
                    For Users obligated to complete a due diligence questionnaire regarding sanctions and embargoes. 

                    Whether the entity and its business units, subsidiaries, and joint ventures have a commercial activity outside of the European Union.

                    Can be:
                    * `0` – False
                    * `1` – True. When set to this value, the next attributes become mandatory. 

                    See the [Sanctions and embargo](/guide/users/legal-entity.html#sanctions-and-embargo) article for more information.
                  enum:
                    - 0
                    - 1
                economicSanctions:
                  type: integer
                  description: |
                    For Users obligated to complete a due diligence questionnaire regarding sanctions and embargoes, and for which the `activityOutsideEu` value is set to `1`.

                    Whether the entity, its subsidiaries, entities, employees, directors, beneficial owners, or joint ventures are subject to Economic Sanctions.

                    Can be:
                    * `0` – False
                    * `1` – True 

                    See the [Sanctions and embargo](/guide/users/legal-entity.html#sanctions-and-embargo) article for more information.
                  enum:
                    - 0
                    - 1
                residentCountriesSanctions:
                  type: integer
                  description: |
                    For Users obligated to complete a due diligence questionnaire regarding sanctions and embargoes, and for which the `activityOutsideEu` value is set to `1`.

                    Whether the entity, its subsidiaries, or joint ventures, located within or operating from any countries or territories are subject to Comprehensive Sanctions. 

                    Can be:
                    * `0` – False
                    * `1` – True 

                    See the [Sanctions and embargo](/guide/users/legal-entity.html#sanctions-and-embargo) article for more information.
                  enum:
                    - 0
                    - 1
                involvedSanctions:
                  type: integer
                  description: |
                    For Users obligated to complete a due diligence questionnaire regarding sanctions and embargoes, and for which the `activityOutsideEu` value is set to `1`.

                    Whether the entity, its subsidiaries, or joint ventures, are engaged in transactions, investments, business, or other dealings that directly or indirectly involve or benefit:
                    * Any countries or territories subject to Comprehensive Sanctions (Cuba, Iran, North Korea, Syria, Crimea, Ukrainian Oblasts not controlled by the government, or Russia), or 
                    * Any person or entity which is the target of any Sanctions (“Sanctioned Targets”).

                    Can be:
                    * `0` – False
                    * `1` – True 

                    See the [Sanctions and embargo](/guide/users/legal-entity.html#sanctions-and-embargo) article for more information.
                  enum:
                    - 0
                    - 1
                entitySanctionsQuestionnaire:
                  type: integer
                  description: |
                    For Users obligated to complete a due diligence questionnaire regarding sanctions and embargoes, and for which the `activityOutsideEu` value is set to `1`.

                    Defines the scope to which the `activityOutsideEu` field applies:
                    * `0` – Not applicable
                    * `1` – Only the legal entity
                    * `2` – The legal entity and all its subsidiaries held at 100%
                    * `3` – The legal entity and all its subsidiaries held at 50% or more
                    * `4` – The legal entity and a list of subsidiaries

                    See the [Sanctions and embargo](/guide/users/legal-entity.html#sanctions-and-embargo) article for more information.

                  enum: [0, 1, 2, 3, 4]
                timezone:
                  type: string
                  description: |
                    The User timezone in the [tz database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) format.
                    The timezones have unique names in the form "Area/Location" (e.g. "America/New_York", "Europe/Paris").

                    It may be used to enforce a card `paymentDailyLimit` based on the cardholder's timezone.
                occupationType:
                  type: string
                  description: Deprecated. Use `occupationCategory` instead.
                  deprecated: True
                  enum:
                    - self_employed
                    - public_sector_employees
                    - private_sector_employees
                    - retired_people_and_students
                    - without_any_professional_activity
                sourceOfFunds:
                  type: string
                  description: The source of funds for opening an account for a company or self-employed person.
                  enum: 
                    - donation
                    - inheritance
                    - loan 
                    - lottery
                    - pension
                    - proceeds_from_investment
                    - proceeds_from_sale
                    - salary
                    - saving
                legalSectorType:
                  type: string
                  description: |
                    Qualify the type of data in the `legalSector` field:
                    * If it is set to NACE the legalSector needs to be in a NACE format (4 digits). 
                    * If it is set to NAF (or not set at all) the legalSector needs to be in a NAF format (4 digits followed by a capital letter).
                  enum:
                    - NAF
                    - NACE
                isOnStockExchange:
                  type: integer
                  description: |
                    The user is a corporation and is quoted on an organized stock exchange.
                    * `0` – No
                    * `1` – Yes
                  enum:
                    - 0
                    - 1
                occupationCategory:
                  type: integer
                  nullable: true
                  description: |
                    Type of occupation of the user. See [Occupation Category](/guide/users/physical.html#occupation-category-occupationcategory) for the list of values.
                  enum: [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]
                personalAssetsRange:
                  type: integer
                  nullable: true
                  description: |
                    The personal assets range of the user. See [Personal Assets Range](/guide/users/physical.html#personal-assets-range-personalassetsrange) for the list of values.
                  enum: [0,1,2,3,4,5,6,7]
                monthlyIncomeRange:
                  type: integer
                  nullable: true
                  description: |
                    Net monthly income of the user. See [Monthly Income Range](/guide/users/physical.html#monthly-income-range-monthlyincomerange) for the list of values.
                  enum: [1,2,3,4,5,6,7]
      responses:
        '200':
          description: OK
          content:
            applicationcjson:
              schema:
                $ref: '#/components/schemas/UserObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
    delete:
      tags:
        - Users
      summary: Disable User
      description: | 
        Update the user Status to `CANCELED`. This action is irreversible. See the [Deletion](/guide/users/modifications.html#deletion) article for more information.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write`, `admin` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`user.cancel`](/guide/users/events.html#user-cancel) |
      operationId: deleteUser
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: userId
          in: path
          description: The unique identifier of the User.
          required: true
          schema:
            type: integer
            example: 12345
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: origin
          in: query
          description: |
            The origin of the request for cancelling the User, which can be one of the following:

            * `OPERATOR` – When you are at the origin of the deactivation.
            * `USER` – When the end user is at the origin of the deactivation.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
          - admin
  /v1/users/{userId}/relationships:
    get:
      summary: Search User Relationships
      description: |
        Retrieve the list of Relationships for a given user.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      tags:
        - User Relationships
      operationId: getUserRelationships
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: userId
          in: path
          description: The unique identifier of the User.
          required: true
          schema:
            type: integer
            example: 12345
        - name: relationshipTypeId
          in: query
          description: | 
            The type of relationship between the source user and the target user. See the [types of relation](/guide/users/relationships.html#types-of-relation).
          schema:
            type: integer
            enum: [1,2,3,4,5,6]
        - name: relationshipTypeName
          in: query
          description: |
            The name of the relationship between the source user and the target user. See the [types of relation](/guide/users/relationships.html#types-of-relation).
          schema:
            type: string
            enum:
              - LEGAL_REPRESENTATIVE
              - EFFECTIVE_BENEFICIARY_SHARES
              - COMPANY_REPRESENTATIVE
              - EMPLOYEE
              - CHILD
        - name: sourceUserId
          in: query
          description: The unique identifier of the source User; holding the relationship.
          schema:
            type: integer
            format: int64
        - name: targetUserId
          in: query
          description: The unique identifier of the target User; linked to the entity.
          schema:
            type: integer
            format: int64
        - name: includeRelationshipTypeIds
          in: query
          description: |
            Comma-separated list of relationship type IDs to include.
            Mutually exclusive with `excludeRelationshipTypeIds`.
          schema:
            type: string
            example: "1,2"
        - name: excludeRelationshipTypeIds
          in: query
          description: |
            Comma-separated list of relationship type IDs to exclude.
            Mutually exclusive with `includeRelationshipTypeIds`.
          schema:
            type: string
            example: "3,4"
        - name: groupBy
          in: query
          description: |
            Groups the results by the specified field. When used, the response format changes to return a `groups` array instead of a flat `relationships` array.

            Pagination applies to groups (i.e., `pageSize` controls the number of groups per page, and `totalCount` reflects the number of distinct groups).
          schema:
            type: string
            enum:
              - targetUserId
              - sourceUserId
              - targetSourcePair
        - name: pageNumber
          in: query
          description: |
            The page number, only available on /v1/ endpoints 
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: pageSize
          in: query
          description: |
            The number of items per page, only available on /v1/ endpoints  
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: |
            Paginated list of relationships. 
            
            The response format depends on whether `groupBy` is used:
            - Without `groupBy`: Returns a flat `relationships` array
            - With `groupBy`: Returns a `groups` array containing nested relationships
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/RelationshipListResponse'
                  - $ref: '#/components/schemas/RelationshipGroupedResponse'
        '404':
          $ref: '#/components/responses/NotFoundError'
      security:
        - OAuth2:
          - read_only
    post:
      summary: Create Relationship
      description: |
        Creates a relationship between the path user and a related user with a given role.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`user.relationship.create`](/guide/users/events.html#user-relationship-create) |
      operationId: createUserRelationship
      tags:
        - User Relationships
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: userId
          in: path
          description: The unique identifier of the User (target of the relationship being created).
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - sourceUserId
                - relationshipTypeId
              properties:
                sourceUserId:
                  type: integer
                  format: int64
                  description: The unique identifier of the user who is the source of the current one (e.g., legal entity, parent).
                relationshipTypeId:
                  type: integer
                  description: | 
                    The type of relationship between the source user and the target user. See the [types of relation](/guide/users/relationships.html#types-of-relation).
                  enum: [1,2,3,4,5,6]
                value:
                  type: string
                  nullable: true
                  description: The value associated with the relationship type, if any.
      responses:
        '201':
          description: Relationship created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserRelationShipObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      security:
        - OAuth2:
          - read_write

  /v1/users/{userId}/relationships/{relationshipId}:
    delete:
      summary: Delete Relationship
      description: |
        Soft-deletes a relationship (sets deleted_at).

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`user.relationship.cancel`](/guide/users/events.html#user-relationship-cancel) |
      operationId: deleteUserRelationship
      tags:
        - User Relationships
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: userId
          in: path
          description: The unique identifier of the User (target of the relationship being deleted).
          required: true
          schema:
            type: integer
            example: 12345
        - name: relationshipId
          in: path
          description: The unique identifier of the relationship
          required: true
          schema:
            type: integer
            example: 12345
      responses:
        '200':
          description: Relationship deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserRelationShipObject'
        '404':
          $ref: '#/components/responses/NotFoundError'
      security:
        - OAuth2:
          - read_write
  
  /v1/users/{userId}/Kycreview:
    put:
      tags:
        - User KYC Review
      summary: Request KYC Review
      operationId: putKycreview
      description: |
        Request a KYC review for a given user and its children to Treezor. Learn more in the [KYC Request](/guide/user-verification/kyc-request.html) article.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`user.kycrequest`](/guide/user-verification/events.html#user-kycrequest) |
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: userId
          in: path
          description: The unique identifier of the User.
          required: true
          schema:
            type: integer
            example: 12345
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserObject'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          example: invalid_request
                        code:
                          type: string
                          example: missing_parameter
                        message: 
                          type: string
                          example: The userId field is required
                        docUrl:
                          type: string
                          example: https://docs.treezor.com/guide/api-basics/response-codes.html 
                        requestId:
                          type: string
                          example: "8392d5dd-dxe2-472f-87cb-b6c77964714f"
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                        code:
                          type: string
                        message:
                          type: string
                        docUrl:
                          type: string
                          example: https://docs.treezor.com/guide/api-basics/response-codes.html 
                        requestId:
                          type: string
                          example: "8392d5dd-dxe2-472f-87cb-b6c77964714f"
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/users/{userId}/kyc:
    get:
      summary: Get User KYC
      description: |
        Retrieve the user KYC information.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      tags:
        - User KYC Review
      operationId: getKyc
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: userId
          in: path
          required: true
          schema:
            type: integer
            format: int64
            description: The unique identifier of the User.
      security:
        - OAuth2:
          - read_only
      responses:
        '200':
          description: User KYC information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  userId:
                    type: integer
                    format: int64
                    description: The unique identifier of the user.
                  clientId:
                    type: integer
                    format: int64
                    description: The unique identifier of the Treezor environment.
                  distributionCountry:
                    type: string
                    nullable: true
                    description: | 
                      The country in which the end user is using your services.
                    format: ISO 3166-1 alpha-2
                    example: "FR"
                    enum:
                      - BE
                      - DE
                      - ES
                      - FR
                      - IT
                      - NL
                  kycLevel:
                    type: integer
                    format: int32
                    deprecated: true
                  kycReview:
                    type: integer
                    format: int32
                    deprecated: true
                  kycReviewComment:
                    type: string
                    nullable: true
                    description: |
                      A comment set by Treezor upon [KYC review](/guide/user-verification/introduction.html).
                  kycStatus:
                    type: string
                    description: |
                      The current verification stage. See [KYC Status](/guide/user-verification/kyc-request.html#statuses-codestatus) for more information.
                    enum:
                      - NONE
                      - PENDING
                      - INCOMPLETE
                      - REFUSED
                      - REVIEW NEEDED
                      - VALIDATED
                      - CANCELED
                  kycReviewType:
                    type: string
                    description: The context of the verification.
                    enum: 
                      - ONBOARDING
                      - PERIODIC
                      - ON_EVENT
                  codeStatus:
                    type: string
                    description: A unique technical code indicating the specific reason for the current status.
                    enum: ["110001","110002","110003","110004","110005","110006","110007"]
                  informationStatus:
                    type: string
                    description: Human-readable information regarding the code status.
                  lastRequestDatetime:
                    type: string
                    format: date-time
                    description: The date and time at which the KYC review for the user was last requested.
                    nullable: true
                    example: "2015-02-25T11:06:39Z"
                  lastReviewDatetime:
                    type: string
                    format: date-time
                    description: The date and time at which the user KYC was last reviewed by Treezor.
                    nullable: true
                    example: "2015-02-27T08:06:39Z"
                  nextReviewDate:
                    type: string
                    format: date
                    description: The date of the next scheduled review. 
                    nullable: true
                    example: "2020-02-25"
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/users/kyc:
    get:
      summary: Search Users KYC
      description: |
        Retrieve the KYC information for all users. Allows filtering by various criteria.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      tags:
        - User KYC Review
      operationId: getKycList
      parameters:
        - name: userId
          in: query
          description: Filter by user unique identifier.
          schema:
            type: integer
            format: int64
        - name: kycLevel
          in: query
          description: |
            Filter by KYC level. Deprecated, use `kycStatus` instead.
          deprecated: true
          schema:
            type: integer
            format: int32
            enum: [0, 1, 2, 3, 4]
        - name: kycReview
          in: query
          description: |
            Filter by KYC review status. Deprecated, use `kycStatus` instead.
          deprecated: true
          schema:
            type: integer
            format: int32
            enum: [0, 1, 2, 3, 4, 5]
        - name: kycStatus
          in: query
          description: Filter by verification status.
          schema:
            type: string
            enum:
              - NONE
              - PENDING
              - INCOMPLETE
              - REFUSED
              - REVIEW NEEDED
              - VALIDATED
              - CANCELED
        - name: kycReviewType
          in: query
          description: Filter by the context of the verification.
          schema:
            type: string
            enum:
              - ONBOARDING
              - PERIODIC
              - ON_EVENT
        - name: distributionCountry
          in: query
          description: Filter by the country in which the end user is using your services.
          schema:
            type: string
            format: ISO 3166-1 alpha-2
            enum:
              - BE
              - DE
              - ES
              - FR
              - IT
              - NL
        - name: nextReviewDateFrom
          in: query
          description: |
            Filter users with next review date on or after this date.
            Format: `YYYY-MM-DD`
          schema:
            type: string
            format: date
            example: "2026-01-01"
        - name: nextReviewDateTo
          in: query
          description: |
            Filter users with next review date on or before this date.
            Format: `YYYY-MM-DD`
          schema:
            type: string
            format: date
            example: "2026-12-31"
        - name: pageNumber
          in: query
          description: The page number for pagination (1-indexed).
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
        - name: pageCount
          in: query
          description: The number of results per page.
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 50
        - name: sortBy
          in: query
          description: The field to sort results by.
          schema:
            type: string
            enum:
              - userId
            default: userId
        - name: sortOrder
          in: query
          description: The sort order for results.
          schema:
            type: string
            enum:
              - ASC
              - DESC
            default: DESC
      security:
        - OAuth2:
          - read_only
      responses:
        '200':
          description: List of users KYC information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    description: Array of user KYC information objects.
                    items:
                      type: object
                      properties:
                        userId:
                          type: integer
                          format: int64
                          description: The unique identifier of the user.
                        clientId:
                          type: integer
                          format: int64
                          description: The unique identifier of the Treezor environment.
                        distributionCountry:
                          type: string
                          nullable: true
                          description: | 
                            The country in which the end user is using your services.
                          format: ISO 3166-1 alpha-2
                          example: "FR"
                          enum:
                            - BE
                            - DE
                            - ES
                            - FR
                            - IT
                            - NL
                        kycLevel:
                          type: integer
                          format: int32
                          deprecated: true
                          description: Deprecated. Use `kycStatus` instead.
                        kycReview:
                          type: integer
                          format: int32
                          deprecated: true
                          description: Deprecated. Use `kycStatus` instead.
                        kycReviewComment:
                          type: string
                          nullable: true
                          description: |
                            A comment set by Treezor upon [KYC review](/guide/user-verification/introduction.html).
                        kycStatus:
                          type: string
                          description: |
                            The current verification stage. See [KYC Status](/guide/user-verification/kyc-request.html#statuses-codestatus) for more information.
                          enum:
                            - NONE
                            - PENDING
                            - INCOMPLETE
                            - REFUSED
                            - REVIEW NEEDED
                            - VALIDATED
                            - CANCELED
                        kycReviewType:
                          type: string
                          description: The context of the verification.
                          enum: 
                            - ONBOARDING
                            - PERIODIC
                            - ON_EVENT
                        codeStatus:
                          type: string
                          description: A unique technical code indicating the specific reason for the current status.
                          enum: ["110001","110002","110003","110004","110005","110006","110007"]
                        informationStatus:
                          type: string
                          description: Human-readable information regarding the code status.
                        lastRequestDatetime:
                          type: string
                          format: date-time
                          description: The date and time at which the KYC review for the user was last requested.
                          nullable: true
                          example: "2025-02-25T11:06:39Z"
                        lastReviewDatetime:
                          type: string
                          format: date-time
                          description: The date and time at which the user KYC was last reviewed by Treezor.
                          nullable: true
                          example: "2025-02-27T08:06:39Z"
                        nextReviewDate:
                          type: string
                          format: date
                          description: The date of the next scheduled review. 
                          nullable: true
                          example: "2026-02-25"
                        totalRows:
                          type: integer
                          format: int64
                          description: |
                            The total number of results matching the query. Only present on the first item of the response.
                          example: 1250
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/users/{userId}/kycliveness:
    post:
      tags:
        - Verification Solutions (KYC)
      description: | 
        Start the Live Verification process, whether it is KYC Liveness or Certified Video. See [Live verification](/guide/user-verification/live-verification.html) for more information.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`kycliveness.create`](/guide/user-verification/events.html#kycliveness-create) (only once the end user completes the process) |
      operationId: postKycliveness
      summary: Initiate Live Verification
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: userId
          in: path
          description: The unique identifier of the user.
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          'application/json':
            schema:
              type: object
              properties:
                redirectUrl: 
                  type: string
                  description: |
                    Specify the URL where the User should be redirected after the Live verification process. This overrides the default configured value.
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  identification:
                    type: array
                    items:
                      type: object
                      properties:
                        identification-id:
                          type: string
                          description: The identifier of the provider's verification session.
                          example: "f8048bee-3182-48dc-93e5-7eef9db77050"
                        identification-url:
                          type: string
                          description: |
                            The URL of the verification process. Expires after 15 minutes.
                          example: "https://id.ubble.ai/f8048bee-3182-48dc-93e5-7eef9db77050"
                        type:
                          type: string
                          description: The type of verification.
                          enum: ["liveness", "video_certified"]
        '400':
          description: |
            Request is invalid i.e., missing userId
          content: {}
            # application/json:
            #   example:
            #     error: invalid request
        '401':
          description: The Authorization header is missing
          content: {}
            # application/json:
            #   example:
            #     error: missing authorization header
        '403':
          description: |
            Your agent is not found in our services
          content: {}
            # application/json:
            #   example:
            #     error: user does not belong to client
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '428':
          description: |
            Specified userId is not found in our services
          content: {}
            # application/json:
            #   example:
            #     error: user not found
        '500':
          description: Internal error
          content: {}
            # application/json:
            #   example:
            #     error: internal server error
        '504':
          description: |
            Internal server error: the request did not respond on time
          content: {}
      security:
        - OAuth2:
          - read_write
          - admin
    put:
      tags:
        - Verification Solutions (KYC)
      summary: Retrieve and Upload Live Verification Result
      description: | 
        Retrieve the live verification results, and make them available to Treezor.
        See [Live verification](/guide/user-verification/live-verification.html) for more information.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`document.create`](/guide/user-verification/events.html#document-create) |
      operationId: put-kyc-liveness
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - name: userId
          in: path
          description: The unique identifier of the user.
          required: true
          schema:
            type: integer
            example: 12345
      responses:
        '200':
          description: 200 response
          content:
            '*/*':
              schema:
                type: object
        '400':
          description: |
            The request is incorrect e.g., missing userId
          content: {}
            # application/json:
            #   example:
            #     error: 'invalid request: invalid user id'
        '401':
          description: The Authorization header is missing
          content: {}
            # application/json:
            #   example:
            #     error: missing authorization header
        '403':
          description: |
            Your agent is not found in our services
          content: {}
            # application/json:
            #   example:
            #     error: agent not found
        '404':
          description: |
            The identification is not found in our services
          content: {}
            # application/json:
            #   example:
            #     error: invalid identification id
        '405':
          description: |
            The documents can not be stored in our services
          content: {}
            # application/json:
            #   example:
            #     error: invalid input
        '406':
          description: |
            The last initiated identification for userId is not in processed state.
          content: {}
          # content:
          #   application/json:
          #     example:
          #       error: invalid identification status
        '410':
          description: The identification no longer exists
          content: {}
        '504':
          description: |
            Internal server error: the request did not respond on time
          content: {}
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
          - admin
  /v1/users/{userId}/qes:
    post:
      tags:
        - Verification Solutions (KYC)
      summary: Initiate QES Verification
      description: |
        Start the qualified electronic signature (QES) verification. 

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`qes.created`](/guide/user-verification/events.html#qes-created) (only once the end user completes the process) |
      operationId: postKycqes
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: userId
          in: path
          description: The unique identifier of the user.
          required: true 
          schema: 
            type: integer
            example: 12345
      requestBody:
        content:
          'application/json':
            schema:
              type: object
              properties:
                  redirectUrl:
                    type: string
                    description: |
                      Specify the URL where the user should be redirected after the QES verification process. This overrides the configured default value.
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  identification:
                    type: object
                    properties:
                      identificationId:
                        type: string
                        description: The identifier of the provider's verification session.
                        example: "TS2-HJKGX"
                      identificationURL:
                        type: string
                        description: |
                          URL to redirect the end user for them to go through the verification process. Expires after 90 days.
                        example: "https://go.test.idnow.de/[...]"
        '400':
          description: Bad request
          content: {}
            # application/json:
            #   example:
            #     error: 'invalid request: invalid user id'
        '401':
          description: Unauthorized
          content: {}
            # application/json:
            #   example:
            #     error: missing authorization header
        '404':
          description: Not found
          content: {}
            # application/json:
            #   example:
            #     error: invalid identification id
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '410':
          description: Gone
          content: {}
            # application/json:
            #   example:
            #     error: invalid input
        '500':
          description: Internal server error
          content: {}
      security:
        - OAuth2:
          - read_write
          - admin
  /v1/users/{userId}/videoconference:
    post:
      tags: 
        - Verification Solutions (KYC)
      summary: Initiate Video Conference Verification
      description: |
        Start the [Video conference verification](/guide/user-verification/videoconf.html) process.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`videoConference.created`](/guide/user-verification/events.html#videoconference-created) (only once the end user completes the process) |
      operationId: postKycVconf
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: userId
          in: path
          description: The unique identifier of the user.
          required: true 
          schema: 
            type: integer
            example: 12345
      requestBody:
        content:
          'application/json':
            schema:
              type: object
              properties:
                redirectUrl:
                  type: string
                  description: |
                    Specify the URL where the user should be redirected after the QES verification process. This overrides the configured default value.
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  identification:
                    type: object
                    properties:
                      identificationId:
                        type: string
                        description: The identifier of the provider's verification session.
                        example: "TS2-HJKGX"
                      identificationURL:
                        type: string
                        description: URL to redirect the end user for them to go through the verification process. Expires after 90 days.
                        example: "https://go.test.idnow.de/[...]"
        '403':
          description: Forbidden
          content: {}
            # application/json:
            #   example:
            #     error: 'unable to create identification: agent not allowed'
        '428':
          description: Precondition Required.
          content: {}
            # application/json:
            #   example:
            #     error: 'unable to create identification: invalid user'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          description: Internal server error
          content: {}
      security:
        - OAuth2:
          - read_write
          - admin
  /v1/users/copy:
    post:
      tags:
        - Verification Solutions (KYC)
      description: | 
        Reuse the result of an identification made with a [Verification solution](/guide/user-verification/introduction.html#verification-solutions). 

        An individual can correspond to several User objects; this is due to the fact that you have to declare hierarchical relationships (for instance, the same person is a legal representative of several legal entities).

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: postKycReuse
      summary: Reuse Verification Result
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          'application/json':
            schema:
              type: object
              required:
                - sourceUserId
                - destinationUserId
              properties:
                sourceUserId:
                  type: integer
                  format: uint64
                  description: The unique identifier of the user to copy the verification result from.
                  example: 12345
                destinationUserId:
                  type: integer
                  format: uint64
                  description: The unique identifier of the user to copy the verification result to.
                  example: 54321
      responses:
        '200':
          description: Identification copied successfully (or already processed).
          content:
            application/json:
              schema:
                type: string
                example: ""
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: |
            Unprocessable Entity — source identification not found in datastore,
            or identification is invalid/not finalized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultError'
              examples:
                storedIdentificationNotFound:
                  summary: No stored identification for source user
                  value:
                    errors:
                      - type: invalid_request
                        code: resource_not_found_error
                        message: "stored identification not found"
                        docUrl: https://docs.treezor.com/guide/api-basics/response-codes.html
                        requestId: "ebcd946c-f22e-4e6c-8775-09714631b06f"
                invalidIdentification:
                  summary: Identification is invalid or not finalized
                  value:
                    errors:
                      - type: invalid_request
                        code: functional_error
                        message: "invalid identification"
                        docUrl: https://docs.treezor.com/guide/api-basics/response-codes.html
                        requestId: "ebcd946c-f22e-4e6c-8775-09714631b06f"
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
    
  /v1/virtualibans:
    get:
      tags:
        - Virtual IBANs
      summary: Search Virtual IBANs
      description: | 
        Retrieve virtual IBANs that match search criteria.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getvirtualibans
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: virtualIbanId
          in: query
          description: The unique identifier of the Virtual IBAN.
          schema:
            type: integer
            example: 12345
        - name: walletId
          in: query
          description: The unique identifier of the Wallet to which the Virtual IBAN is associated.
          schema:
            type: integer
            example: 12345
        - name: typeId
          in: query
          description: The type of the Virtual IBAN.
          schema:
            type: integer
            enum: [1, 2]
        - name: tag
          in: query
          description: |
            Custom attribute that you can use as you see fit.
            
            Learn more in the [Object tags](/guide/api-basics/objects-tags.html) article.
          schema:
            type: integer
        - name: reference
          in: query
          description: The client's internal reference of the Virtual IBAN.
          schema:
            type: string
        - name: validFrom
          in: query
          description: |
            The date from which the Virtual IBAN validity starts. Defaults to today's date and must be set in the future.

            Format: `YYYY-MM-DD`
          schema:
            type: string
            format: date
            example: "2025-01-01"
        - name: validTo
          in: query
          description: |
            The date from which the Virtual IBAN validity ends. Must be set after the `validFrom` date.

            Format: `YYYY-MM-DD`
          schema:
            type: string
            format: date
            example: "2025-01-01"
        - name: maxUsage
          in: query
          description: The maximum number of transactions allowed.
          schema:
            type: integer
            example: 5
        - name: maxAmount
          in: query
          description: The maximum cumulated amount allowed.
          schema:
            type: string
            format: float
            example: "23.99"
        - name: numberOfTransactions
          in: query
          description: The current number of transactions for the Virtual IBAN.
          schema:
            type: integer
            example: 3
        - name: cumulatedAmount
          in: query
          description: The cumulated amount of transactions for the Virtual IBAN.
          schema:
            type: string
            format: float
            example: "1000.00"
        - name: createdDateFrom
          in: query
          description: |
            The creation date from which you want to filter the request result.

            Format: `YYYY-MM-DD HH:mm:ss`
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2025-01-01 12:00:00"
        - name: createdDateTo
          in: query
          description: |
            The creation date up to which you want to filter the request result.

            Format: `YYYY-MM-DD HH:mm:ss`
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2025-01-01 12:00:00"
        - name: updatedDateFrom
          in: query
          description: |
            The modification date from which you want to filter the request result. 
            
            Format: `YYYY-MM-DD HH:mm:ss`
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2025-01-01 12:00:00"
        - name: updatedDateTo
          in: query
          description: |
            The modification date up to which you want to filter the request result. 
            
            Format: `YYYY-MM-DD HH:mm:ss` 
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2025-01-01 12:00:00"
        - name: pageNumber
          in: query
          description: |
            The page number, only available on /v1/ endpoints 
          schema:
            type: integer
        - name: pageCount
          in: query
          description: |
            The number of items per page, only available on /v1/ endpoints  
          schema:
            type: integer
        - name: sortBy
          in: query
          description: |
            The transaction element you want to sort the list with.
          schema:
            type: string
            default: "createdDate"
        - name: sortOrder
          in: query
          description: |
            The order you want to sort the list.
            * **DESC** for descending.
            * **ASC** for ascending.
          schema:
            type: string
            default: DESC
            enum:
              - ASC
              - DESC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualIbanObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    post:
      tags:
        - Virtual IBANs
      summary: Create Virtual IBAN
      description: | 
        Create a new virtual IBAN associated with a given Wallet.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: postVirtualIban
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - walletId
                - typeId
              type: object
              properties:
                walletId:
                  type: integer
                  description: |
                    The unique identifier of the Wallet to which the Virtual IBAN is associated. Must be a `walletType` of `9` or `10`.
                typeId:
                  type: integer
                  description: |
                    The type of IBAN, allowing for a specific transfer direction. 
                    Can be: <ul><li>`1` for `SDDR` [SEPA Direct Debit](/guide/transfers/direct-debit.html)</li><li>`2` for `SCTR` [SEPA Credit Transfer](/guide/transfers/credit-transfer.html#received-credit-transfers-sctr)</li></ul>
                  enum: [1, 2]
                tag:
                  type: string
                  description: |
                    Custom attribute that you can use as you see fit.
                    
                    Learn more in the [Object tags](/guide/api-basics/objects-tags.html) article.
                validFrom:
                  type: string
                  description: |
                    The date from which the Virtual IBAN validity starts. Defaults to today's date and must be set in the future.
                    
                    Format: `YYYY-MM-DD`
                validTo:
                    type: string
                    description: |
                      The date from which the Virtual IBAN validity ends. Must be set after the `validFrom` date.
                      
                      Format: `YYYY-MM-DD`
                maxUsage:
                  type: integer
                  description: |
                    The maximum number of transactions allowed (`0` = unlimited). 
                maxAmount:
                  type: string
                  format: number
                  description: | 
                    The maximum cumulated amount of all transactions (`"0.00"` = unlimited).
                reference:
                  type: string
                  maxLength: 255
                  description: |
                    Custom field for your internal reference of the Virtual IBAN.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualIbanObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/virtualibans/{virtualIbanId}:
    get:
      tags:
        - Virtual IBANs
      summary: Get Virtual IBAN
      description: | 
        Retrieve a Virtual IBAN based on its `id`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getvirtualiban
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: virtualIbanId
          in: path
          description: The unique identifier of the Virtual IBAN.
          required: true
          schema:
            type: integer
            example: 12345
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualIbanObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    put:
      tags:
        - Virtual IBANs
      summary: Update Virtual IBAN
      description: | 
        Update a Virtual IBAN's information.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: putVirtualIban
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: virtualIbanId
          in: path
          description: The unique identifier of the Virtual IBAN.
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                validFrom:
                  type: string
                  description: |
                    The date from which the Virtual IBAN validity starts. Defaults to today's date and must be set in the future.
                    
                    Format: `YYYY-MM-DD`
                validTo:
                    type: string
                    description: |
                      The date from which the Virtual IBAN validity ends. Must be set after the `validFrom` date.
                      
                      Format: `YYYY-MM-DD`
                maxUsage:
                  type: integer
                  description: |
                    The maximum number of transactions allowed (`0` = unlimited). 
                maxAmount:
                  type: string
                  format: number
                  description: | 
                    The maximum cumulated amount of all transactions (`"0.00"` = unlimited).
                reference:
                  type: string
                  maxLength: 255
                  description: |
                    Custom field for your internal reference of the Virtual IBAN.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualIbanObject'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/wallets:
    get:
      tags:
        - Wallets
      summary: Search Wallets
      description: |
        Retrieve Wallets that match your search conditions. The request must specify at least one of those fields: `walletId`, `userId`, or `walletTypeId`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getWallets
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: walletId
          in: query
          description: The unique identifier of the Wallet.
          schema:
            type: integer
            example: 12345
        - name: walletStatus
          in: query
          description: | 
            The status of the Wallet, which can be one of the following:
            * `CANCELED` – The Wallet is deactivated.
            * `PENDING` – The Wallet has just been created.
            * `VALIDATED` – The Wallet is active.
          schema:
            type: string
            enum:
              - CANCELED
              - PENDING
              - VALIDATED
        - name: userId
          in: query
          description: The unique identifier of the User owning the Wallet.
          schema:
            type: integer
            example: 12345
        - name: parentUserId
          in: query
          description: The unique identifier of the Parent User of the Wallet owner.
          schema:
            type: integer
            example: 12345
        - name: walletTag
          in: query
          description: |
            Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
            
            Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
          schema:
            type: string
            maxLength: 250
        - name: walletTypeId
          in: query
          description: |
            The type of Wallet. The following values are allowed:
            * `9` – Electronic Money Wallet
            * `10` – Payment Account Wallet
            
            Other types are available but can only be set by Treezor. Learn more in the [Wallet Types](/guide/wallets/introduction.html#types-of-wallets) documentation.
          schema:
            type: integer
            enum: [9,10,15]
        - name: walletTypeIdList
          in: query
          description: | 
            The list of `walletTypeId` to take into account. 
            
            Must be associated with the `userId` query parameter and is ignored if the `walletTypeId` parameter is provided.

            Learn more about wallet types in the [Wallet Types](/guide/wallets/introduction.html#types-of-wallets) documentation.
          schema:
            type: array
            items:
              type: integer
              enum: [9,10,15]
        # - name: eventAlias
        #   in: query
        #   deprecated: true
        #   description: |
        #     Legacy attribute, do not use.
        #   schema:
        #     type: string
        - name: tariffId
          in: query
          description: The fees applied to the Wallet, as defined by your contract with Treezor.
          schema:
            type: integer
            example: 123
        - name: pageNumber
          in: query
          description: |
            The page number, only available on /v1/ endpoints 
          schema:
            type: integer
        - name: pageCount
          in: query
          description: |
            The number of items per page, only available on /v1/ endpoints  
          schema:
            type: integer
        - name: sortBy
          in: query
          description: |
            The transaction element you want to sort the list with.
          schema:
            type: string
            default: createdDate
        - name: sortOrder
          in: query
          description: |
            The order you want to sort the list.
            * **DESC** for descending.
            * **ASC** for ascending.
          schema:
            type: string
            default: DESC
            enum:
              - ASC
              - DESC
        - name: createdDateFrom
          in: query
          description: |
            The creation date from which you want to filter the request result.
            
            Format: `YYYY-MM-DD HH:mm:ss`.
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2024-04-23 04:34:23"
        - name: createdDateTo
          in: query
          description: |
            The creation date up to which you want to filter the request result.

            Format: `YYYY-MM-DD HH:mm:ss`.
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2024-04-23 04:34:23"
        - name: updatedDateFrom
          in: query
          description: |
            The modification date from which you want to filter the request result. 
            
            Format: `YYYY-MM-DD HH:mm:ss`. 
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2024-04-23 04:34:23"
        - name: updatedDateTo
          in: query
          description: |
            The modification date up to which you want to filter the request result. 
            
            Format: `YYYY-MM-DD HH:mm:ss`.
          schema:
            type: string
            # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            example: "2024-04-23 04:34:23"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'  
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
    post:
      tags:
        - Wallets
      summary: Create Wallet
      description: | 
        Create a new Wallet.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`wallet.create`](/guide/wallets/events.html#wallet-create) |
      operationId: postWallets
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - walletTypeId
                - userId
                - currency
                - eventName
              type: object
              properties:
                walletTypeId:
                  type: integer
                  description: |
                    The type of Wallet. The following values are allowed:
                    * `9` – Electronic Money Wallet
                    * `10` – Payment Account Wallet
                  
                    Other types are available but can only be set by Treezor. Learn more in the [Wallet Types](/guide/wallets/introduction.html#types-of-wallets) documentation.
                  enum: [9,10]
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                userId:
                  type: integer
                  description: The unique identifier of the User owning the Wallet.
                bic:
                  type: string
                  description: |
                    The [BIC](/guide/overview/glossary.html#bank-identifier-code-bic) of the Wallet, indicating in which country the wallet is domiciled. 
                    
                    This value may be required depending on your configuration. Learn more in the [Local IBAN](/guide/wallets/iban.html#local-iban) article.
                  enum: ["TRZOFR21XXX","TRZODEB2XXX","TRZOITM2XXX","TRZOESM2XXX"]
                # jointUserId:
                #   type: integer
                #   deprecated: true
                #   description: Legacy attribute, do not use.
                walletTag:
                  type: string
                  maxLength: 250
                  description: |
                    Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
                    
                    Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
                currency:
                  type: string
                  description: |
                    The currency of the Wallet, used for transactions.
                    
                    Format: [ISO 4217 3-letter code](/guide/api-basics/data-format.html#currencies)
                  example: "EUR"
                eventName:
                  type: string
                  description: The name of the Wallet.
                  example: "Main Wallet"
                eventAlias:
                  type: string
                  deprecated: true
                  description: Legacy attribute, do not use.
                eventMessage:
                  type: string
                  description: Can be used to describe the Wallet.
                  example: "This is a description of the Main Wallet."
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /v1/wallets/{walletId}:
    get:
      tags:
        - Wallets
      summary: Get Wallet
      description: | 
        Retrieve a Wallet based on its `id`.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getWallet
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: walletId
          in: path
          description: The unique identifier of the Wallet.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletObject'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
    put:
      tags:
        - Wallets
      summary: Update Wallet
      description: | 
        Modify a Wallet information.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-session |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`wallet.update`](/guide/wallets/events.html#wallet-update) |
      operationId: putWallet
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: walletId
          in: path
          description: The unique identifier of the Wallet.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                walletTypeId:
                  type: integer
                  description: |
                    The type of Wallet. Can only be updated if no transaction occurred with the Wallet yet.
                    
                    The following values are allowed:
                    * `9` – Electronic Money Wallet
                    * `10` – Payment Account Wallet
                  
                    Other types are available but can only be set by Treezor. Learn more in the [Wallet Types](/guide/wallets/introduction.html#types-of-wallets) documentation.
                  enum: [9,10]
                walletTag:
                  type: string
                  maxLength: 250
                  description: |
                    Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.

                    Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
                eventName:
                  type: string
                  description: The name of the Wallet.
                  example: "Main Wallet"
                eventMessage:
                  type: string
                  description: Can be used to describe the Wallet.
                  example: "This is a description of the Main Wallet."
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
    delete:
      tags:
        - Wallets
      summary: Delete Wallet
      description: |
        Change the status of the Wallet to `CANCELED`. This is only possible if the following prerequisites are met:
        * The Balance must be equal to `0`
        * No operations can be pending

        This action is irreversible.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`wallet.cancel`](/guide/wallets/events.html#wallet-cancel) |
      operationId: deleteWallet
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: walletId
          in: path
          description: The unique identifier of the Wallet.
          required: true
          schema:
            type: integer
            example: 12345
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: origin
          in: query
          required: true
          description: |
            The origin of the request for cancelling the Wallet, which can be one of the following:
            * `OPERATOR` – When **you** are at the origin of the deactivation.
            * `USER` – When the **end user** is at the origin of the deactivation.
          schema:
            type: string
            enum: ["OPERATOR","USER"]
        - name: originId
          in: query
          description: |
            The unique identifier related to the origin of the cancellation.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - origin
              properties:
                accessTag:
                  type: string
                  maxLength: 250
                  description: |
                    A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
                origin: 
                  type: string
                  description: |
                    The origin of the request for cancelling the Wallet, which can be one of the following: <ul><li>`OPERATOR` – When **you** are at the origin of the deactivation.</li><li>`USER` – When the **end user** is at the origin of the deactivation.</li></ul>
                  enum: ["OPERATOR","USER"]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /simulation/payout-sddr:
    post:
      summary: Simulate SDDR Core
      operationId: SimulateSDDR
      description: Simulate a received SEPA Direct Debit into one of your Wallet in Sandbox.
      tags:
        - Payouts
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                debitorIban:
                  type: string
                  description: IBAN or Virtual IBAN of the debited Wallet.
                amount:
                  type: string
                typeSDD:
                  type: string
                  enum: 
                    - CORE
                    - B2B
                typeReject:
                  type: string
                  description: | 
                    The type of error returned if the SDDR fails. Defaults to `rejected`.
                  enum:
                    - rejected
                    - returned
                    - refunded
                    - today
                  default: "rejected"
                sci:
                  type: string
                  description: The SEPA Credit Identifier of the user. In the case of simulation, this defaults to a random string.
                nbTxs:
                  type: integer
                  description: |
                    The number of transactions for the SDD.
                  default: 1
                mandateId:
                  type: string
                  description: The unique identifier of the Mandate
                executeAfterParse:
                  type: integer
                  enum:
                    - 0
                    - 1
      responses:
        '204':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Information regarding the error.
                  data:
                    type: object
                    properties:
                      clientId:
                        type: integer
                      debitorIban:
                        type: string
                        example: "FR7616798000010000071474474"
                      amount:
                        type: string
                      mandateId:
                        type: string
                      typeReject:
                        type: string
                        enum:
                          - rejected
                          - returned
                          - refunded
                          - today
                      typeSDD:
                        type: string
                        enum: 
                          - CORE
                          - B2B
                      sci:
                        type: string
                      nbTxs:
                        type: integer
      security:
        - OAuth2: 
          - admin
          # verified scope
  /simulation/payouts/{payoutId}:
    put:
      summary: Simulate SCTE Update
      description: |
        Simulate the approval / refusal of a standard emitted SEPA Credit Transfer (SCTE).

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `admin` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`payout.update`](/guide/transfers/events.html#payout-update) |
      operationId: putSimuScte
      tags:
        - Payouts
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - in: path
          schema: 
            type: string
          name: payoutId
          required: true
          description: The unique identifier of the payout.
      requestBody:
        content:
          application/json:
            schema: 
              required:
                - payoutStatus
              type: object
              properties:
                payoutStatus:
                  type: string
                  description: |
                    The simulated status of the payout. Can be:
                      * `CANCELED` – The message will be rejected
                      * `VALIDATED` – The SCTE will be accepted
                  enum: ["CANCELED", "VALIDATED"]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  payoutId:
                    type: string
                    description: The unique identifier of the payout.
                    example: "12345"
                  payoutStatus:
                    type: string
                    description: The status of the payout.
                    enum: ["CANCELED", "VALIDATED"]
                  payoutTypeId:
                    type: integer
                    description: | 
                      The type of payout. In this simulation context, can only be `1` for SEPA Credit Transfer.
                    example: 1
                  payoutTag:
                    type: string
                    maxLength: 250
                    description: |
                      Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.

                      Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - admin
  /simulation/payouts/bulk:
    put:
      summary: Simulate SCTE Mass Update
      description: |
        Simulate the approval / refusal of multiple standard emitted SEPA Credit Transfers (SCTE).

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`payout.update`](/guide/transfers/events.html#payout-update) |
      operationId: putSimuScteBulk
      tags:
        - Payouts
      #parameters: 
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - updates
              type: object
              properties:
                updates:
                  type: array
                  items:
                    required:
                      - payoutIds
                      - payoutStatus
                    type: object
                    properties:
                      payoutIds:
                        type: array
                        items:
                          type: string
                          description: |
                            The unique identifier of the payout.
                          example: "12345"
                      payoutStatus:
                        type: string
                        description: |
                          The simulated status of the payout. Can be:
                            * `CANCELED` – The message will be rejected
                            * `VALIDATED` – The SCTE will be accepted
                        enum: ["CANCELED", "VALIDATED"]
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  updates:
                    type: array
                    items:
                      type: object
                      properties:
                        payoutId:
                          type: string
                          description: The unique identifier of the payout.
                          example: "12345"
                        payoutStatus:
                          type: string
                          description: The status of the payout.
                          enum:
                            - CANCELED
                            - PENDING
                            - VALIDATED
                        payoutTypeId:
                          type: integer
                          description: | 
                              The type of payout. In this simulation context, can only be `1` for SEPA Credit Transfer.
                          enum: [1]
                        payoutTag:
                          type: string
                          maxLength: 250
                          description: |
                            Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
                            Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        message:
                          type: string
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/BadRequestError'
      security:
        - OAuth2:
          - read_write
  /simulation/payin-sct:
    post:
      tags:
        - Payins
      summary: Simulate SCTR
      operationId: simulateSctReception
      description: Simulate the reception of a SEPA Credit Transfer into one of your Wallet in Sandbox.
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - iban
                - amount
              properties:
                iban:
                  type: string
                  description: The IBAN of the recipient Wallet.
                  example: "FR7616798000010001726649397"
                amount:
                  type: number
                  description: The amount to credit the recipient Wallet.
                  example: 20.15
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: The identifier of the simulation.
                    example: 23055
                  txId:
                    type: string
                    example: "8bBx3BodW8cNhlWL"
                    description: The transaction identifier.
                  payinId:
                    type: integer
                    example: 1646614
                    description: The unique identifier of the resulting Payin.
                  returnReasonCode:
                    type: string
                    nullable: true
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: integer
                  errorMessage:
                    type: string
                    description: Detailed information about the error.
                    example: "Input validation failed"
                  additionalInformation:
                    type: array
                    description: List of strings indicating the issue.
                    items: {}
      security:
        - OAuth2: 
          - admin
  /simulation/sct-inst/payin:
    post:
      tags:
        - Payins
      summary: Simulate SCTR Inst
      operationId: simulateSctInstReception
      description: Simulate the reception of an instantaneous SEPA Credit Transfer into one of your Wallet in Sandbox.
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - bic
                - iban
                - currency
                - amount
              properties:
                iban:
                  type: string
                  description: The IBAN of the recipient wallet.
                  example: "FR7616798000010000071474474"
                bic:
                  type: string
                  description: BIC of the recipient wallet.
                  example: "TRZOFR21XXX"
                name:
                  type: string
                  description: Name of the recipient wallet owner.
                  example: "Alex Oak"
                currency:
                  type: string
                  description: | 
                    Currency of the of the transfer. Can only be `EUR`.
                  example: "EUR"
                amount:
                  type: number
                  format: float
                  description: Amount of the transfer.
                  example: 25.33
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  sctInstID:
                    type: string
                    nullable: false
                    example: 1220c2ac-d0ad-51e9-bbb2-6f5484fe4308
                  paymentID:
                    type: string
                    nullable: false
                    example: RECEPTION590cf804-7c2d-11f0-bf45-0289d4be696d
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                    description: Reason for the error.
                    example: "BAD REQUEST"
                  details:
                    type: string
                    description: Detailed information about the error.
                    example: "name required"
      security:
        - OAuth2: 
          - admin
          # verified scope
  /simulation/sct-inst/recall:
    post:
      tags:
        - Recalls
      summary: Simulate SCT Inst recall
      description: Simulate a recall for an instantaneous SEPA Credit Transfer.
      operationId: simulateSctInstRecall
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                sctInstId:
                  type: string
                demandDate:
                  type: string
                reasonCode:
                  type: string
                additionalInformation:
                  type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  externalRecallId:
                    type: string
                    nullable: false
                  recallrId:
                    type: string
                    nullable: false
                  sctInstId:
                    type: string
                    nullable: false
                  paymentId:
                    type: string
                    nullable: false
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2: 
          - admin
          # verified scope
  /simulation/acquiring/payin:
    post:
      summary: Simulate Acquiring Payin
      description: Simulate operations resulting from the card acquisition feature.
      operationId: SimulateAcquiringPayin
      tags:
        - Acquiring (Simulation)
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: number
                  format: float
                  nullable: false
                walletId:
                  type: number
                  format: float
                  nullable: false
                amount:
                  type: number
                  format: float
                  nullable: false
                currency:
                  type: string
                  nullable: false
                  default: EUR
                status:
                  type: number
                  format: float
                  nullable: false
                transactionReference:
                  type: string
                  nullable: true
      responses:
        '204':
          description: OK
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2: 
          - admin
  /simulation/international-transfer/payin:
    post:
      summary: Simulate International Transfer Reception
      description: | 
        Emulates the reception of an an international payin transfer
      tags: 
        - Payins
      operationId: simulateInternationalPayin
      requestBody:
        content:
          application/json:
            schema:
              required:
                - recipient
                - sender
                - instructedAmount
                - exchangeRate
              type: object
              properties:
                recipient:
                  type: object
                  description: Recipient details
                  properties:
                    account:
                      type: string
                      description: Recipient IBAN
                      example: "FR7616798000010000361692945"
                sender:
                  type: object
                  description: Sender details
                  properties:
                    account:
                      type: string
                      description: Sender IBAN
                      example: "GB29NWBK60161331926819"
                    address:
                      type: string
                      description: Sender postal address
                      example: "24 High Street Little Whinging London United Kingdom"
                    bankCode:
                      type: object
                      description: Identification bancaire de l'établissement émetteur.
                      properties:
                        type:
                          type: string
                          description: Bank code type
                          example: "BIC"
                        value:
                          type: string
                          description: Bank code value
                          example: "CMCIFRPAXXX"
                    name:
                      type: string
                      description: Sender name
                      example: "John Doe"
                instructedAmount:
                  type: object
                  description: Source Amount
                  properties:
                    currency:
                      type: string
                      description: Instructed amount currency (ISO 4217)
                      example: "GBP"
                    value:
                      type: number
                      format: float
                      description: Amount
                      example: 13
                exchangeRate:
                  type: number
                  description: Exchange rate
                  example: 9.34
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayinObject'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /simulation/international-transfer/sweep:
    post:
      summary: Simulation of International Transfer Validation
      description: |
        Enables to emulate international payin validation
      operationId: simulateInternationalPayinValidation
      tags:
        - Payins
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - payins
              properties:
                payins:
                  type: array
                  description: |
                    International payins to be validated
                  items:
                    type: string
                    format: uuid
                    description: International payin reference
                  example: 
                    - "ebcd946c-f22e-4e6c-8775-09714631b06f"
                    - "27f3d236-913c-452c-a9ca-aeb6fe62eac3"
                  minItems: 1
      responses:
        '204':
          description: No content
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /simulation/operations:
    post:
      summary: Simulate Operations
      description: | 
        Create fake operations for a given Wallet. This may prove useful to test [Account Statements](/guide/wallets/account-statements.html) for instance.
      operationId: simulateOperations
      tags:
        - Operations
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                walletId:
                  type: string
                  description: The unique identifier of the Wallet for which operations are to be emulated.
                date:
                  type: string
                  description: | 
                    The month on which the fake operations are going to be created. Format: `YYYY-MM`
                  example: "2024-10"
                operations:
                  type: object
                  properties:
                    payin:
                      type: integer
                      description: The number of payin operations to generate.
                    payinrefund:
                      type: integer
                      description: The number of payin refunds to generate. Must be lower than or equal to the number of payins.
                    payout:
                      type: integer
                      description: The number of payout operations to generate.
                    payoutrefund:
                      type: integer
                      description: The number of payout refunds to generate. Must be lower than or equal to the number of payouts.
                    transfer:
                      type: integer
                      description: The number of wallet-to-wallet transfers to generate.
                    transferrefund:
                      type: integer
                      deprecated: true
                      description: Deprecated. Don't use.
                    cardtransaction:
                      type: integer
                      description: The number of card transaction operations to generate.
                    transferfees:
                      type: integer
                      description: The number of wallet-to-wallet transfers to generate with a `transferTypeId` of `3`.
                    transfercreditnote:
                      type: integer
                      description: The number of wallet-to-wallet transfers to generate with a `transferTypeId` of `4`.
      responses:
        '201':
          description: Created
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - admin
          # verified scope
  /simulation/cardtransaction/authorization:
    post:
      summary: Simulate Authorization
      operationId: simuTransacAuthorization
      description: |
        Simulate a card transaction authorization.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `admin` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`cardtransaction.create`](/guide/cards/events-tx.html#authorized-cardtransaction-create) |
      tags:
        - Card Transactions
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - cardId
                - payment
              properties:
                cardDigitalizationExternalId:
                  type: integer
                  format: uint32
                  description: The digitized card unique identifier.
                cardId:
                  type: integer
                  format: uint32
                  description: The card unique identifier.
                exemptionType3ds:
                  type: string
                  description: |
                    The reason why the card transaction was exempted of 3DS. See [list](/guide/cards/transactions.html#_3ds-exemption-type-exemptiontype3ds).
                  enum: ["0","1","2","3","4","5","6","7","8","9","A","C","D","M","O","R","T","V"]
                  default: "0"
                merchant:
                  type: object
                  properties:
                    id:
                      type: string
                      description: The merchant unique identifier.
                    name:
                      type: string
                      description: The merchant name.
                    city:
                      type: string
                      description: The merchant city.
                    countryCode:
                      type: string
                      format: ISO 3166-1 alpha 3
                      example: FRA
                      description: The merchant country code.
                    mcc:
                      type: string
                      description: The merchant category code.
                    acquirerId:
                      type: string
                      description: The merchant acquirer ID.
                    street:
                      type: string
                      description: The merchant street.
                    postalCode:
                      type: string
                      description: The merchant postal code.
                    posCountryCode:
                      type: string
                      format: ISO 3166-1 alpha 3
                      example: FRA
                      description: The merchant point of sale country code.
                    posTerminalId:
                      type: string
                      format: ISO 8583
                      description: |
                        The identifier of the terminal used for the transaction.
                      example: "B1234567"
                      minLength: 1
                      maxLength: 8
                partialApproval:
                  type: boolean
                  description: Indicates if you want to have a partial approval authorization.
                  default: false
                payment:
                  type: object
                  required:
                    - category
                    - amount
                  properties:
                    amount:
                      type: integer
                      format: int64
                      description: Amount expressed in the smallest unit of the Euro currency.
                    category:
                      type: string
                      description: The type of card transaction.
                      enum: ["ecommerce","chip","contactless","contactlessOnlinePin","atm"]
                    localAmount:
                      type: integer
                      format: uint64
                      description: The positive local amount expressed in the smallest unit of the given currency. Defaults to the `amount` value.
                    localCurrency:
                      type: string
                      format: ISO 4217 alpha-3
                      description: The local amount currency.
                      default: "EUR"
                    localDate:
                      type: string
                      format: RFC 3339 date-time
                      example: 2006-01-02T15:04:05+07:00
                      description: The authorization local date.
                requestDate:
                  type: string
                  format: RFC 3339 date-time
                  example: 2006-01-02T15:04:05+07:00
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  cardTransactionId:
                    type: integer
                    format: uint32
                    description: The unique identifier of the card transaction.
                  paymentStatus:
                    type: string
                    description: The type of CardTransaction. In the specific case of simulation, allowed values are.
                    enum: [ "A", "I"]
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500': 
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - admin
  /simulation/cardtransaction/clearing:
    post:
      summary: Simulate Settlement
      operationId: simuTransacClearing
      description: |
        Simulates the settlement of the card transaction. The transaction amount will be computed using authorized amount and reversed authorized amount.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `admin` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`cardtransaction.create`](/guide/cards/events-tx.html#card-transaction-events) |
      tags:
        - Card Transactions
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - cardId
                - cardTransactionId
              properties:
                cardId:
                  type: integer
                  format: uint32
                  description: The card unique identifier.
                cardTransactionId:
                  type: integer
                  format: uint32
                  description: | 
                    The unique identifier of the authorization card transaction. The `paymentStatus` must be `A` or `V`.
                amount:
                  type: integer
                  format: int64
                  description: |
                    Amount expressed in the smallest unit of the Euro currency. If not set, defaults to full amount of the authorization.
                    The amount must be less or equal than the authorized amount.
      responses:
        '204':
          description: Successfully created.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - admin
  /simulation/cardtransaction/reversal:
    post:
      summary: Simulate Reversal
      operationId: simuTransacReversal
      description: |
        Simulates a card authorization reversal transaction.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `admin` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`cardtransaction.create`](/guide/cards/events-tx.html#card-transaction-events) |
      tags:
        - Card Transactions
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - cardId
                - cardTransactionId
              properties:
                cardId:
                  type: integer
                  format: uint32
                  description: The card unique identifier.
                cardTransactionId:
                  type: integer
                  format: uint32
                  description: The unique identifier of the authorization card transaction. The `paymentStatus` must be `A`.
                amount:
                  type: integer
                  format: int64
                  description: |
                    Amount expressed in the smallest unit of the Euro currency. 
                    This field is optional and defaults to the total amount of the authorization. 
                    Indicating an amount allows you to simulate a partial reversal.
      responses:
        '204':
          description: Successfully created.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - admin
  /v1/mdc/rulesets:
    get:
      tags:
      - Card Rulesets (MDC)
      operationId: get-rulesets
      summary: Get Rulesets
      description: Retrieve all rulesets.
      security:
        - OAuth2: []
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  nextPageToken:
                    type: string
                    nullable: true
                  rulesetsShort:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                          description: The unique identifier of the ruleset.
                          example: "9ea4c7f6-50a2-4679-8634-dfe42f03cbdc"
                        name:
                          type: string
                          description: The name of the ruleset.
                          example: "month total amount rule"
                        status:
                          type: string
                          enum: ["ENABLED"]
                          description: The status of the ruleset.
                        description:
                          type: string
                          description: The description of the ruleset.
                          example: "check if total amount exceeds 100 euros"
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - Card Rulesets (MDC)
      operationId: create-ruleset
      summary: Create Ruleset
      description: Create a Ruleset.
      security:
        - OAuth2: []
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          'application/json':
            schema:
              type: object
              properties:
                metadata:
                  type: object
                  required:
                    - name
                  properties:
                    name:
                      type: string
                      description: The name of the ruleset.
                      example: "month total amount rule"
                    description:
                      type: string
                      description: The description of the ruleset.
                      example: "Check if total amount exceeds 100 euros"
                    walletId:
                      type: string
                      description: The unique identifier of the wallet to debit.
                    priority:
                      type: integer
                      description: |
                        The priority of the rule in case of conflicting rules. The higher the value, the higher the priority. This field is required if the `walletId` is provided.
                      maximum: 100
                ruleset:
                  type: object
                  required:
                  - attributes
                  - decisions
                  properties:
                    attributes:
                      type: array
                      items:
                        type: object
                        required:
                        - name
                        - type
                        properties:
                          name:
                            type: string
                            description: |
                              The name of the [Fact](https://treezor.zendesk.com/hc/en-us/articles/13231619074844-Multi-Criteria-Dynamic-Card-MDC#h_01HSTA05STRHTNH7FZV2H10Y1Q).
                          type:
                            type: string
                            description: The type of the fact.
                    decisions:
                      type: array
                      items:
                        type: object
                        required:
                        - conditions
                        - event
                        properties:
                          conditions:
                            type: object
                            description: |
                              Decision tree associating [Facts](https://treezor.zendesk.com/hc/en-us/articles/13231619074844-Multi-Criteria-Dynamic-Card-MDC#h_01HSTA05STRHTNH7FZV2H10Y1Q), 
                              [Operators](https://treezor.zendesk.com/hc/en-us/articles/13231619074844-Multi-Criteria-Dynamic-Card-MDC#h_01HSTA09CW4QCEQ50PTSCZP4P6), and values.
                            properties:
                              all:
                                type: array
                                items:
                                  type: object
                              any:
                                type: array
                                items:
                                  type: object
                          event:
                            type: object
                            required:
                            - params
                            - type
                            properties:
                              type:
                                type: string
                              params:
                                type: object
                                properties: {}
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  rulesetId:
                    type: string
                    example: 200cf363-32cd-4edd-a9ff-bc4aee6ba070
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/mdc/rulesets/{rulesetId}:
    get:
      tags:
      - Card Rulesets (MDC)
      operationId: get-ruleset
      summary: Get Ruleset
      description: Retrieve a Ruleset with its `id`.
      security:
        - OAuth2: []
      parameters:
      #- $ref: '#/components/parameters/Authorization'
      - name: rulesetId
        in: path
        description: The unique identifier of the Ruleset.
        required: true
        schema:
          type: string
          format: uuid
          example: "9ea4c7f6-50a2-4679-8634-dfe42f03cbdc"
      responses:
        '200':
          description: OK
          content: 
            'application/json':
              schema:
                type: object
                properties:
                  metadata:
                    type: object
                    properties:
                      name:
                        type: string
                        description: The name of the ruleset.
                        example: "month total amount rule"
                      description:
                        type: string
                        description: The description of the ruleset.
                        example: "Check if amount exceeds 100 euros"
                      status:
                        type: string
                        enum: ["ENABLED"]
                        description: The status of the ruleset.
                      rulesetId:
                        type: string
                        format: uuid
                        description: The unique identifier of the ruleset.
                        example: 200cf363-32cd-4edd-a9ff-bc4aee6ba070
                  ruleset:
                    type: object
                    required:
                    - attributes
                    - decisions
                    properties:
                      attributes:
                        type: array
                        items:
                          type: object
                          required:
                          - name
                          - type
                          properties:
                            name:
                              type: string
                              description: |
                                The name of the [Fact](https://treezor.zendesk.com/hc/en-us/articles/13231619074844-Multi-Criteria-Dynamic-Card-MDC#h_01HSTA05STRHTNH7FZV2H10Y1Q).
                            type:
                              type: string
                              description: The type of the fact.
                      decisions:
                        type: array
                        items:
                          type: object
                          required:
                          - conditions
                          - event
                          properties:
                            conditions:
                              type: object
                              description: |
                                Decision tree associating [Facts](https://treezor.zendesk.com/hc/en-us/articles/13231619074844-Multi-Criteria-Dynamic-Card-MDC#h_01HSTA05STRHTNH7FZV2H10Y1Q), 
                                [Operators](https://treezor.zendesk.com/hc/en-us/articles/13231619074844-Multi-Criteria-Dynamic-Card-MDC#h_01HSTA09CW4QCEQ50PTSCZP4P6), and values.
                              properties:
                                all:
                                  type: array
                                  items:
                                    type: object
                                any:
                                  type: array
                                  items:
                                    type: object
                            event:
                              type: object
                              required:
                              - params
                              - type
                              properties:
                                type:
                                  type: string
                                params:
                                  type: object
                                  properties: {}
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Card Rulesets (MDC)
      operationId: put-ruleset
      summary: Update Ruleset
      description: Modify a Ruleset.
      security:
        - OAuth2: []
      parameters:
      #- $ref: '#/components/parameters/Authorization'
      - name: rulesetId
        in: path
        description: The unique identifier of the Ruleset.
        required: true 
        schema:
          type: string
          format: uuid
          example: "9ea4c7f6-50a2-4679-8634-dfe42f03cbdc"
      requestBody:
        content:
          'application/json':
            schema:
              type: object
              properties:
                metadata:
                  type: object
                  required:
                  - name
                  properties:
                    name:
                      type: string
                      description: The name of the ruleset.
                      example: "month total amount rule"
                    description:
                      type: string
                      description: The description of the ruleset.
                      example: "Check if amount exceeds 100 euros"
                    walletId:
                      type: string
                      description: The unique identifier of the wallet to debit.
                    priority:
                      type: integer
                      description: |
                        The priority of the rule in case of conflicting rules. The higher the value, the higher the priority. This field is required if the `walletId` is provided.
                      maximum: 100
                ruleset:
                  type: object
                  required:
                  - attributes
                  - decisions
                  properties:
                    attributes:
                      type: array
                      items:
                        type: object
                        required:
                        - name
                        - type
                        properties:
                          name:
                            type: string
                            description: |
                              The name of the [Fact](https://treezor.zendesk.com/hc/en-us/articles/13231619074844-Multi-Criteria-Dynamic-Card-MDC#h_01HSTA05STRHTNH7FZV2H10Y1Q).
                          type:
                            type: string
                            description: The type of the fact.
                    decisions:
                      type: array
                      items:
                        type: object
                        required:
                        - conditions
                        - event
                        properties:
                          conditions:
                            type: object
                            description: |
                              Decision tree associating [Facts](https://treezor.zendesk.com/hc/en-us/articles/13231619074844-Multi-Criteria-Dynamic-Card-MDC#h_01HSTA05STRHTNH7FZV2H10Y1Q), 
                              [Operators](https://treezor.zendesk.com/hc/en-us/articles/13231619074844-Multi-Criteria-Dynamic-Card-MDC#h_01HSTA09CW4QCEQ50PTSCZP4P6), and values.
                            properties:
                              all:
                                type: array
                                items:
                                  type: object
                              any:
                                type: array
                                items:
                                  type: object
                          event:
                            type: object
                            required:
                            - params
                            - type
                            properties:
                              type:
                                type: string
                              params:
                                type: object
                                properties: {}
        required: true
      responses:
        '204':
          description: No Content
          content: {}
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
      - Card Rulesets (MDC)
      summary: Disable Ruleset
      description: Disable a Ruleset.
      operationId: disable-ruleset
      security:
        - OAuth2: []
      parameters:
      #- $ref: '#/components/parameters/Authorization'
      - name: rulesetId
        in: path
        description: The unique identifier of the Ruleset.
        required: true
        schema:
          type: string
          format: uuid
          example: "9ea4c7f6-50a2-4679-8634-dfe42f03cbdc"
      responses:
        '204':
          description: No content
          content: {}
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/mdc/{cardId}/rulesets:
    get:
      tags:
      - Card Rulesets (MDC)
      operationId: get-ruleset-from-card
      summary: Retrieve Card Rulesets
      description: Get all rulesets assigned to a given card.
      security:
        - OAuth2: []
      parameters:
      #- $ref: '#/components/parameters/Authorization'
      - name: cardId
        in: path
        description: The unique identifier of the Card.
        required: true
        schema:
          type: string
          example: "12345"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    rulesetId:
                      type: string
                      format: uuid
                      description: The unique identifier of the ruleset.
                      example: "404b794e-6e19-495a-bd21-51d5adb82b94"
                    metadata:
                      type: object
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - Card Rulesets (MDC)
      summary: Assign Rulesets
      description: Assign rulesets to a given card.
      operationId: attach-ruleset-to-card
      security:
        - OAuth2: []
      parameters:
      #- $ref: '#/components/parameters/Authorization'
      - name: cardId
        in: path
        description: The unique identifier of the Card.
        required: true
        schema:
          type: string
          example: "12345"
      requestBody:
        content:
          'application/json':
            schema:
              type: array
              items:
                type: object
                required:
                - metadata
                - rulesetId
                properties:
                  rulesetId:
                    type: string
                    format: uuid
                    description: The unique identifier of the ruleset.
                    example: "404b794e-6e19-495a-bd21-51d5adb82b94"
                  metadata:
                    type: object
        required: true
      responses:
        '201':
          description: Created
          content: {}
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/mdc/{cardId}/ruleset/{rulesetId}/factsBalance:
    get:
      tags:
        - Card Rulesets (MDC)
      summary: Retrieve Ruleset virtual balance
      description: Retrieve a ruleset virtual balance.
      operationId: getFactsBalance
      security:
        - OAuth2: []
      parameters:
      #- $ref: '#/components/parameters/Authorization'
      - name: cardId
        in: path
        description: The unique identifier of the Card.
        required: true
        schema:
          type: string
          example: "12345"
      - name: rulesetId
        in: path
        description: The unique identifier of the Ruleset.
        required: true
        schema:
          type: string
          format: uuid
          example: "9ea4c7f6-50a2-4679-8634-dfe42f03cbdc"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  facts:
                    type: object
                    properties:
                      month_total_amount:
                        type: object
                        properties:
                          definedValue:
                            type: integer
                            example: 50
                          consumedValue:
                            type: integer
                            example: 0
                          remainingValue:
                            type: integer
                            example: 50
                  error:
                    type: string
                    nullable: true
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /v1/mdc/mccLists:
    post:
      tags:
        - MCC Lists (MDC)
      summary: Create MCC List
      operationId: postMdcMccList
      description: |
        Create a list of Merchant Category Codes for the [Multi-Criteria Dynamic Card (MDC)](/guide/cards/transactions-rules-engine.html) feature.
      #parameters:
      #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type: string
                  description: The description of the list.
                  example: "mcc_partners_whitelist"
                  nullable: true
                  maxLength: 255
      responses:
        '201':
          description: MCC List Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MccList'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
      security:
        - OAuth2: []
    get:
      tags:
       - MCC Lists (MDC)
      summary: Get all MCC Lists
      description: |
        Retrieve all the Merchant Category Code Lists for the [Multi-Criteria Dynamic Card](/guide/cards/transactions-rules-engine.html) feature.
      operationId: getMdcMccLists
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: nextPageToken
          in: query
          schema:
            type: string
            nullable: true
          description: The pagination cursor to use as a query parameter to get to the next page of results.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MccLists'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2: []
  /v1/mdc/mccLists/{id}:
    parameters:
      - name: id
        in: path
        description: The unique identifier of the MCC List.
        required: true
        schema:
          type: string
          format: uuid
          example: "ec4896e4-21d3-45ab-8071-68a3b6c88002"
    get:
      tags:
        - MCC Lists (MDC)
      summary: Get MCC List
      operationId: getMdcMccList
      description: |
        Retrieve a Merchant Category Code List for the [Multi-Criteria Dynamic Card](/guide/cards/transactions-rules-engine.html) feature based on its `id`.
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      responses:
        '400':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MccList'
      security:
        - OAuth2: []
    put:
      tags:
        - MCC Lists (MDC)
      summary: Update MCC List
      operationId: updateMdcMccList
      description: |
        Update a Merchant Category Code List for the [Multi-Criteria Dynamic Card](/guide/cards/transactions-rules-engine.html) feature.
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type: string
                  description: The description of the list.
                  example: "mcc_partners_whitelist"
                  nullable: true
                  maxLength: 255
      responses:
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '200':
          description: a MCCList
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MccList'
      security:
        - OAuth2: []
    delete:
      tags:
        - MCC Lists (MDC)
      summary: Delete MCC List
      operationId: deleteMdcMccList
      description: |
        Delete a Merchant Category Code List for the [Multi-Criteria Dynamic Card](/guide/cards/transactions-rules-engine.html) feature.
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      responses:
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '204':
          description: List successfully removed
      security:
        - OAuth2: []
  /v1/mdc/mccLists/{id}/codes:
    parameters:
      - name: id
        in: path
        description: The unique identifier of the mccList.
        required: true
        schema:
          type: string
          format: uuid
          example: "ec4896e4-21d3-45ab-8071-68a3b6c88002"
    post:
      tags:
       - MCC Lists (MDC)
      summary: Import MCCs
      operationId: importMdcMccListCodes
      description: |
       Import MCC values asynchronously into a Merchant Category Code Lists for the [Multi-Criteria Dynamic Card](/guide/cards/transactions-rules-engine.html) feature.
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                codes:
                  type: array
                  description: List of MIDs to import.
                  items:
                    type: string
                    maxLength: 4
                    example: "3009"
      responses:
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '202':
          description: Import in progress
      security:
        - OAuth2: []
  /v1/mdc/mccLists/{id}/codes/{mcc}:
    parameters:
      - name: id
        in: path
        description: The unique identifier of the MCC List.
        required: true
        schema:
          type: string
          format: uuid
          example: "7b447d57-414f-401f-a9a0-f2789a55f966"
      - name: mcc
        in: path
        description: The merchant category code.
        required: true
        schema:
          type: string
          example: "3009"
          maxLength: 4
    put:
      tags:
        - MCC Lists (MDC)
      summary: Add MCC to MCC List
      operationId: addMdcMccListCode
      description: Add the MCC in the Merchant Category Code list.
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      responses:
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '204':
          description: MCC added to list
      security:
        - OAuth2: []
    get:
      tags:
        - MCC Lists (MDC)
      summary: Check MCC Presence
      operationId: checkMdcMccListCode
      description: Check in the MCC is included in the MCC List. If not, the API returns an HTTP 404 error.
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      responses:
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '204':
          description: The MCC is in the list
      security:
        - OAuth2: []
    delete:
      tags:
        - MCC Lists (MDC)
      summary: Remove MCC from List
      operationId: removeMdcMccListCode
      description: Remove the MCC from the MCC List. If the code isn't in the list, the API returns an HTTP 404 error.
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      responses:
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '204':
          description: MCC removed from list
      security:
        - OAuth2: []
  /v1/mdc/midLists:
    post:
      tags:
        - MID Lists (MDC)
      summary: Create Merchant Id List
      operationId: postMdcMidList
      description: |
        Create a list of Merchant Ids for the [Multi-Criteria Dynamic Card (MDC)](/guide/cards/transactions-rules-engine.html) feature.
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type: string
                  nullable: true
                  maxLength: 255
                  description: The description of the list.
                  example: "mid_partners_whitelist"
      responses:
        '201':
          description: MerchantId List Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantIdList'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
      security:
        - OAuth2: []
    get:
      tags:
        - MID Lists (MDC)
      summary: Get all MID Lists
      description: |
        Retrieve all the Merchant Id Lists for the [Multi-Criteria Dynamic Card](/guide/cards/transactions-rules-engine.html) feature.
      operationId: getMdcMidLists
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: nextPageToken
          in: query
          schema:
            type: string
            nullable: true
          description: The pagination cursor to use as a query parameter to get to the next page of results.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantIdLists'
        '405':
          $ref: '#/components/responses/NotAllowedError'
      security:
        - OAuth2: []
  /v1/mdc/midLists/{id}:
    parameters:
      - name: id
        in: path
        description: The unique identifier of the MID List.
        required: true
        schema:
          type: string
          format: uuid
          example: "7b447d57-414f-401f-a9a0-f2789a55f966"
    get:
      tags:
        - MID Lists (MDC)
      summary: Get MID List
      operationId: getMidMccList
      description: |
        Retrieve a Merchant Id List for the [Multi-Criteria Dynamic Card](/guide/cards/transactions-rules-engine.html) feature based on its `id`.
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      responses:
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantIdList'
      security:
        - OAuth2: []
    put:
      tags:
        - MID Lists (MDC)
      summary: Update MerchantId List
      operationId: updateMdcMidList
      description: |
        Update a Merchant Id List for the [Multi-Criteria Dynamic Card](/guide/cards/transactions-rules-engine.html) feature.
      #parameters:
       #- $ref: '#/components/parameters/Authorization'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type: string
                  nullable: true
                  description: The description of the list.
                  example: "mid_partners_whitelist"
                  maxLength: 255
      responses:
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '200':
          description: a MerchantIdList
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantIdList'
      security:
        - OAuth2: []
    delete:
      tags:
        - MID Lists (MDC)
      summary: Delete MerchantId List
      operationId: deleteMdcMidList
      description: |
        Delete a Merchant Id List for the [Multi-Criteria Dynamic Card](/guide/cards/transactions-rules-engine.html) feature.
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      responses:
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '204':
          description: List successfully removed
      security:
        - OAuth2: []
  /v1/mdc/midLists/{id}/merchantIds:
    parameters:
     # - $ref: '#/components/parameters/Authorization'
      - name: id
        in: path
        description: The unique identifier of the MID List.
        required: true
        schema:
          type: string
          format: uuid
          example: "7b447d57-414f-401f-a9a0-f2789a55f966"
    post:
      tags:
        - MID Lists (MDC)
      summary: Import MIDs
      operationId: importMdcMidListCodes
      description: |
        Import MCC values asynchronously into a Merchant Category Code Lists for the [Multi-Criteria Dynamic Card](/guide/cards/transactions-rules-engine.html) feature.
      #parameters:
      #  - $ref: '#/components/parameters/Authorization'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantIds:
                  type: array
                  description: List of MIDs to import.
                  items:
                    type: string
                    example: "173490000000001"
      responses:
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '202':
          description: Import in progress
      security:
        - OAuth2: []
  /v1/mdc/midLists/{id}/merchantIds/{mid}:
    parameters:
      - name: id
        in: path
        description: The unique identifier of the MID List.
        required: true
        schema:
          type: string
          format: uuid
          example: "7b447d57-414f-401f-a9a0-f2789a55f966"
      - name: mid
        in: path
        description: The merchant id.
        required: true
        schema:
          type: string
          example: "173490000000001"
    put:
      tags:
        - MID Lists (MDC)
      summary: Add MID to MID List
      operationId: addMdcMidListCode
      description: Add the MID in the Merchant Id list.
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      responses:
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '204':
          description: MerchantId added to list
      security:
        - OAuth2: []
    get:
      tags:
        - MID Lists (MDC)
      summary: Check MID Presence
      operationId: checkMdcMidListCode
      description: Check in the MCC is included in the MCC List.
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      responses:
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '204':
          description: The MerchantId is in the list
      security:
        - OAuth2: []
          
    delete:
      tags:
        - MID Lists (MDC)
      summary: Remove MID from List
      operationId: removeMdcMidListCode
      description: Remove the MID from the MID List.
      responses:
        '404':
          $ref: '#/components/responses/NotFoundError'
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '204':
          description: MerchantId removed from list
      security:
        - OAuth2: []
          
  /v1/cardDigitalizations:
    get:
      tags:
        - Cards Digitalization
      summary: Search Card Digitalizations
      description: Search for card digitalizations.
      operationId: readcardDigitalizations
      deprecated: true
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: accessTag
          in: query
          description: |
            A unique identifier used to enforce [Idempotency](/guide/api-basics/idempotency.html).
          schema:
            type: string
            maxLength: 250
        - name: filter
          in: query
          description: |
            Filterable fields are: 
            - `cardId`
            - `createdDate`
            - `detailsFromGPS`
            - `externalId`
            - `id`
            - `modifiedDate`
            - `status`
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  cardDigitalizations:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        cardId:
                          type: string
                        externalId:
                          type: integer
                        status:
                          type: string
                          description: |
                            | Status | Description |
                            | ---- | ----------- |
                            | A | Active |
                            | U | Not tokenized |
                            | S | Suspended |
                            | D (or X) | Deactivated (Final status, cannot be changed)|
                        createdDate:
                          type: string
                        modifiedDate:
                          type: string
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2: []
  /v1/cardDigitalizations/{id}:
    get:
      tags:
        - Cards Digitalization
      summary: Get Card Digitalization
      description: Retrieve a Card Digitalization based on its `id`.
      operationId: cardDigitalizationsId
      deprecated: true
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: id
          in: path
          description: Card digitalization internal id.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  cardDigitalizations:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        cardId:
                          type: integer
                        externalId:
                          type: integer
                        status:
                          type: string
                          description: |
                            | Status | Description |
                            | ---- | ----------- |
                            | A | Active |
                            | U | Not tokenized |
                            | S | Suspended |
                            | D (or X) | Deactivated (Final status, cannot be changed)|
                        createdDate:
                          type: string
                        modifiedDate:
                          type: string
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2: []
    put:
      tags:
        - Cards Digitalization
      summary: Update Payment Token Status
      description: | 
        Update the status of a payment Token

        This endpoint requires per-operation [SCA](/guide/strong-customer-authentication/introduction.html).
      operationId: putcardDigitalizationsId
      deprecated: true
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: id
          in: path
          description: Card digitalization internal id.
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
        - name: status
          in: query
          description: |
            The new status for the payment Token. Possible values are:

            | Status | Description |
            | ---- | ----------- |
            | unsuspend | Unsuspend |
            | suspend | Suspend |
          required: true
          schema:
            type: string
            enum: ["unsuspend", "suspend"]
        - name: reasonCode
          in: query
          description: |
            The reason code for the action. Possible values are:

            For a suspension:

            | Reason code | Description |
            | ---- | ----------- |
            | L | Cardholder confirmed token device lost |
            | S | Cardholder confirmed token device stolen |
            | T | Issuer or cardholder confirmed fraudulent token transactions |
            | Z | Other |

            For an unsuspension:

            | Reason code | Description |
            | ---- | ----------- |
            | F | Cardholder reported token device found or not stolen |
            | T | Issuer or cardholder confirmed no fraudulent token transactions |
            | Z | Other |
          required: true
          schema:
            type: string
            enum: ["F","L","S","T","Z"]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  cardDigitalizations:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        cardId:
                          type: integer
                        externalId:
                          type: integer
                        status:
                          type: string
                          description: |
                            | Status | Description |
                            | ---- | ----------- |
                            | A | Active |
                            | U | Not tokenized |
                            | S | Suspended |
                            | D (or X) | Deactivated (Final status, cannot be changed)|
                        createdDate:
                          type: string
                        modifiedDate:
                          type: string
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2: []
    delete:
      tags:
        - Cards Digitalization
      summary: Delete Payment Token
      description: Delete a payment Token
      operationId: deletecardDigitalizationsId
      deprecated: true
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: id
          in: path
          description: The unique identifier of the Card Digitalization (internal).
          required: true
          schema:
            type: integer
            format: int64
            example: 12345
        - name: reasonCode
          in: query
          description: |
            The reason code for the action. Possible values are:

            | Reason code | Description |
            | ---- | ----------- |
            | C | Account closed |
            | F | Issuer or cardholder confirmed fraudulent token transactions (Deprecated) |
            | L | Cardholder confirmed token device lost |
            | S | Cardholder confirmed token device stolen |
            | T | Issuer or cardholder confirmed fraudulent token transactions |
            | Z | Other |
          required: true
          schema:
            type: string
            enum: ["C","F","L","S","T","Z"]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  cardDigitalizations:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        cardId:
                          type: string
                        externalId:
                          type: integer
                        status:
                          type: string
                          description: |
                            | Status | Description |
                            | ---- | ----------- |
                            | A | Active |
                            | U | Not tokenized |
                            | S | Suspended |
                            | D (or X) | Deactivated (Final status, cannot be changed)|
                        createdDate:
                          type: string
                        modifiedDate:
                          type: string
        '405':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2: []
  /core-connect/scheduledPayment:
    post:
      tags:
        - Scheduled Payments
      summary: Create Scheduled Payment
      description: | 
        Schedule a Payout or a Wallet-to-Wallet transfer for a future date.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | Per-operation |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: postScheduledPayment
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - walletId
                - beneficiaryType
                - beneficiary
                - amount
                - type
                - currency
              type: object
              properties:
                scheduledPaymentName:
                  type: string
                  description: The label describing the goal of the Scheduled Payment.
                walletId:
                  type: integer
                  description: The unique identifier of the Wallet to debit.
                beneficiaryType:
                  type: string
                  description: |
                    The type of beneficiary for the operation, which can be:
                    * `payout` – The Scheduled Payment targets an external account.
                    * `walletTransfer` – The Scheduled Payment targets another Wallet in your Treezor environment.
                  enum:
                    - payout
                    - walletTransfer
                beneficiary:
                  type: integer
                  description: |
                    The unique identifier of the beneficiary of the Scheduled Payment, which can be either `beneficiaryId` for Payouts or `beneficiaryWalletId` for Wallet-to-Wallet transfers.
                amount:
                  type: number
                  format: float
                  description: The amount of the Scheduled Payment.
                  example: 24.99
                type:
                  type: string
                  description: | 
                    The type of Scheduled Payment, which can be: 
                    * `oneshot` – The payment will occur only once.
                    * `periodic` – The payment will occur periodically over a defined timeframe.
                  enum:
                    - oneshot
                    - periodic
                execAt:
                  type: string
                  format: date
                  description: |
                    The date on which the a `oneshot` Scheduled Payment is to be executed. This date must be set at least one day in the future. Format: `YYYY-MM-DD`.
                  example: "2027-12-12"
                startAt:
                  type: string
                  format: date
                  description: |
                    The date from which a `periodic` Scheduled Payment execution starts. This date must be set at least one day in the future. Format: `YYYY-MM-DD`.
                  example: "2025-12-12"
                endAt:
                  type: string
                  format: date
                  description: |
                    The date on which a `periodic` Scheduled Payment ends. This date must be set after the `startAt` date. Format: `YYYY-MM-DD`.
                  example: "2027-12-12"
                period:
                  type: string
                  description: |
                    The frequency at which a `periodic` Scheduled Payment is to occur.
                  enum:
                    - weekly
                    - monthly
                    - quarterly
                    - bi-annual
                    - annual
                beneficiaryLabel:
                  type: string
                  maxLength: 140
                  description: The label that will be displayed for the Scheduled Payments, regardless of the type.
                currency:
                  type: string
                  format: ISO-4217
                  description: | 
                    The currency of the Scheduled Payments. Can only be `EUR`.
                  example: "EUR"
                endToEndId:
                  type: string
                  maxLength: 24
                  description: The end-to-end identifier, for Payouts only.
      responses:
        '200':
          description: OK – Scheduled payment created
          content:
            application/json:
              schema:
                title: ScheduledPayment
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: The unique identifier of the Scheduled Payment order.
                    example: "9ea4c7f6-50a2-4679-8634-dfe42f03cbdc"
                  status:
                    type: string
                    description: The status of the Scheduled Payment.
                    enum:
                      - CANCELED
                      - VALIDATED
                  scheduledPaymentName:
                    type: string
                    description: The label describing the goal of the Scheduled Payment.
                  walletId:
                    type: integer
                    description: The unique identifier of the Wallet to be debited.
                  beneficiaryType:
                    type: string
                    description: |
                      The type of beneficiary for the operation.
                    enum:
                      - payout
                      - walletTransfer
                  beneficiary:
                    type: integer
                    description: |
                      The unique identifier of the beneficiary of the Scheduled Payment, which can be either `beneficiaryId` for Payouts or `beneficiaryWalletId` for Wallet-to-Wallet transfers.
                  amount:
                    type: number
                    format: float
                    description: The amount of the Scheduled Payment.
                    example: 24.99
                  type:
                    type: string
                    description: | 
                      The type of Scheduled Payment, which can be: 
                      * `oneshot` – The payment will occur only once.
                      * `periodic` – The payment will occur periodically over a defined timeframe.
                    enum:
                      - oneshot
                      - periodic
                  execAt:
                    type: string
                    format: date
                    description: |
                      The date on which the a `oneshot` Scheduled Payment is to be executed. This date must be set at least one day in the future. Format: `YYYY-MM-DD`.
                    example: "2027-12-12"
                  startAt:
                    type: string
                    format: date
                    description: |
                      The date from which a `periodic` Scheduled Payment execution starts. This date must be set at least one day in the future. Format: `YYYY-MM-DD`.
                    example: "2025-12-12"
                  endAt:
                    type: string
                    format: date
                    description: |
                      The date on which a `periodic` Scheduled Payment ends. This date must be set after the `startAt` date. Format: `YYYY-MM-DD`.
                    example: "2027-12-12"
                  creationDate:
                    type: string
                    format: date-time
                    description: The date and time at which the Scheduled Payment was created.
                    example: "2024-02-26T01:50:08+00:00"
                  period:
                    type: string
                    description: |
                      The frequency at which a `periodic` Scheduled Payment is to occur.
                    enum:
                    - weekly
                    - monthly
                    - quarterly
                    - bi-annual
                    - annual
                  beneficiaryLabel:
                    type: string
                    maxLength: 140
                    description: The label that will be displayed for the Scheduled Payments, regardless of the type.
                  currency:
                    type: string
                    format: ISO-4217
                    description: | 
                      The currency of the Scheduled Payments. Can only be `EUR`.
                    example: "EUR"
                  userId:
                    type: string
                    description: The unique identifier of the User owning the Wallet to debit.
                  amr:
                    type: array
                    description: | 
                      The type of SCA for per-operation SCA (e.g., `CLOUD_PIN`, `HYBRID_PIN`, `DEVICE_BIOMETRIC`).
                    items: 
                      type: string
                      example: "DEVICE_BIOMETRIC"
                  failedPayment:
                    type: array
                    items: 
                      type: object
                      properties:
                        date:
                          type: string
                        errorCode:
                          type: string
                        errorMessage:
                          type: string
                  endToEndId: 
                    type: string
                    maxLength: 24
                    description: |
                      The end-to-end identifier, for Payouts only.  
                    
                      Allowed characters: alphanumeric and `/` `-` `?` `:` `(` `)` `.` `,` `+` ` ` (space). 
                      
                      Musn't start nor end with `/`, and musn't contain `//`.
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
    get:
      tags:
        - Scheduled Payments
      summary: Get Scheduled Payment
      description: |
        Retrieve Scheduled Payment orders based on the corresponding `userId` and/or `walletId`

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getScheduledPayment
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: userId
          in: query
          description: The unique identifier of the Wallet to be debited.
          schema:
            type: integer
            example: 12345
        - name: walletId
          in: query
          description: The unique identifier of the User owning the Wallet to debit.
          schema:
            type: integer
            example: 12345
        - name: cursor
          in: query
          description: Pagination cursor, if you don't pass a cursor, result will start at the first page.
          schema:
            type: string
            example: "da4b9237bacccdf19c0760cab7aec4a8359010b0"
        - name: pageSize
          in: query
          description: Number of results per page.
          schema:
            type: number
      responses:
        '200':
          description: OK – Scheduled payment created
          content:
            application/json:
              schema:
                title: ScheduledPayment
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: The unique identifier of the Scheduled Payment order.
                  status:
                    type: string
                    description: The status of the Scheduled Payment.
                    enum:
                      - CANCELED
                      - VALIDATED
                  scheduledPaymentName:
                    type: string
                    description: The label describing the goal of the Scheduled Payment.
                  walletId:
                    type: integer
                    description: The unique identifier of the Wallet to be debited.
                  beneficiaryType:
                    type: string
                    description: |
                      The type of beneficiary for the operation.
                    enum:
                      - payout
                      - walletTransfer
                  beneficiary:
                    type: integer
                    description: |
                      The unique identifier of the beneficiary of the Scheduled Payment, which can be either `beneficiaryId` for Payouts or `beneficiaryWalletId` for Wallet-to-Wallet transfers.
                  amount:
                    type: number
                    format: float
                    description: The amount of the Scheduled Payment.
                  type:
                    type: string
                    description: | 
                      The type of Scheduled Payment, which can be: 
                      * `oneshot` – The payment will occur only once.
                      * `periodic` – The payment will occur periodically over a defined timeframe.
                    enum:
                      - oneshot
                      - periodic
                  execAt:
                    type: string
                    format: Y-m-d
                    description: |
                      The date on which the a `oneshot` Scheduled Payment is to be executed. This date must be set at least one day in the future. Format: YYYY-MM-DD.
                  startAt:
                    type: string
                    format: Y-m-d
                    description: |
                      The date from which a `periodic` Scheduled Payment execution starts. This date must be set at least one day in the future. Format: YYYY-MM-DD.
                  endAt:
                    type: string
                    format: Y-m-d
                    description: |
                      The date on which a `periodic` Scheduled Payment ends. This date must be set after the `startAt` date. Format: YYYY-MM-DD.
                  ccreationDate:
                    type: string
                    format: date-time
                    description: The date and time at which the Scheduled Payment was created.
                    example: "2024-02-26T01:50:08+00:00"
                  period:
                    type: string
                    description: |
                      The frequency at which a `periodic` Scheduled Payment is to occur.
                    enum:
                    - weekly
                    - monthly
                    - quarterly
                    - bi-annual
                    - annual
                  beneficiaryLabel:
                    type: string
                    maxLength: 140
                    description: The label that will be displayed for the Scheduled Payments, regardless of the type.
                  currency:
                    type: string
                    format: ISO-4217
                    description: | 
                      The currency of the Scheduled Payments. Can only be `EUR`.
                    example: "EUR"
                  userId:
                    type: string
                    description: The unique identifier of the User owning the Wallet to debit.
                  amr:
                    type: array
                    description: | 
                      The type of SCA for per-operation SCA (e.g., `CLOUD_PIN`, `HYBRID_PIN`, `DEVICE_BIOMETRIC`).
                    items: 
                      type: string
                      example: "DEVICE_BIOMETRIC"
                  failedPayment:
                    type: array
                    items: 
                      type: object
                      properties:
                        date:
                          type: string
                        errorCode:
                          type: string
                        errorMessage:
                          type: string
                  endToEndId: 
                    type: string
                    maxLength: 24
                    description: |
                      The end-to-end identifier, for Payouts only.  
                      
                      Allowed characters: alphanumeric and `/` `-` `?` `:` `(` `)` `.` `,` `+` ` ` (space).
                      
                      Musn't start nor end with `/`, and musn't contain `//`.
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
  /core-connect/scheduledPayment/{scheduledPaymentId}:
    delete:
      tags:
        - Scheduled Payments
      summary: Delete Scheduled Payment
      description: |
        Cancel a Scheduled Payment order.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: deleteScheduledPayment
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: scheduledPaymentId
          in: path
          description: The unique identifier of the Scheduled Payment order.
          required: true
          schema:
            type: string
            example: "12345"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                title: ScheduledPayment
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: The unique identifier of the Scheduled Payment order.
                  status:
                    type: string
                    description: The status of the Scheduled Payment.
                    example: CANCELED
                    enum:
                      - CANCELED
                      - VALIDATED
                  scheduledPaymentName:
                    type: string
                    description: The label describing the goal of the Scheduled Payment.
                  walletId:
                    type: integer
                    description: The unique identifier of the Wallet to be debited.
                  beneficiaryType:
                    type: string
                    description: |
                      The type of beneficiary for the operation.
                    enum:
                      - payout
                      - walletTransfer
                  beneficiary:
                    type: integer
                    description: |
                      The unique identifier of the beneficiary of the Scheduled Payment, which can be either `beneficiaryId` for Payouts or `beneficiaryWalletId` for Wallet-to-Wallet transfers.
                  amount:
                    type: number
                    format: float
                    description: The amount of the Scheduled Payment.
                  type:
                    type: string
                    description: | 
                      The type of Scheduled Payment, which can be: 
                      * `oneshot` – The payment will occur only once.
                      * `periodic` – The payment will occur periodically over a defined timeframe.
                    enum:
                      - oneshot
                      - periodic
                  execAt:
                    type: string
                    format: date
                    description: |
                      The date on which the a `oneshot` Scheduled Payment is to be executed. This date must be set at least one day in the future. Format: `YYYY-MM-DD`.
                    example: "2027-12-12"
                  startAt:
                    type: string
                    format: date
                    description: |
                      The date from which a `periodic` Scheduled Payment execution starts. This date must be set at least one day in the future. Format: `YYYY-MM-DD`.
                    example: "2025-12-12"
                  endAt:
                    type: string
                    format: date
                    description: |
                      The date on which a `periodic` Scheduled Payment ends. This date must be set after the `startAt` date. Format: `YYYY-MM-DD`.
                    example: "2027-12-12"
                  creationDate:
                    type: string
                    format: date-time
                    description: The date and time at which the Scheduled Payment was created.
                    example: "2024-02-26T01:50:08+00:00"
                  period:
                    type: string
                    description: |
                      The frequency at which a `periodic` Scheduled Payment is to occur.
                    enum:
                    - weekly
                    - monthly
                    - quarterly
                    - bi-annual
                    - annual
                  beneficiaryLabel:
                    type: string
                    maxLength: 140
                    description: The label that will be displayed for the Scheduled Payments, regardless of the type.
                  currency:
                    type: string
                    format: ISO-4217
                    description: | 
                      The currency of the Scheduled Payments. Can only be `EUR`.
                    example: "EUR"
                  userId:
                    type: string
                    description: The unique identifier of the User owning the Wallet to debit.
                  amr:
                    type: array
                    description: | 
                      The type of SCA for per-operation SCA (e.g., `CLOUD_PIN`, `HYBRID_PIN`, `DEVICE_BIOMETRIC`).
                    items: 
                      type: string
                      example: "DEVICE_BIOMETRIC"
                  failedPayment:
                    type: array
                    items: 
                      type: object
                      properties:
                        date:
                          type: string
                        errorCode:
                          type: string
                        errorMessage:
                          type: string
                  endToEndId: 
                    type: string
                    maxLength: 24
                    description: |
                      The end-to-end identifier, for Payouts only.  
                    
                      Allowed characters: alphanumeric and `/` `-` `?` `:` `(` `)` `.` `,` `+` ` ` (space). 
                      
                      Musn't start nor end with `/`, and musn't contain `//`.
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_write
  /core-connect/scheduledPayment/{scheduledPaymentId}/payments:
    get:
      tags:
        - Scheduled Payments
      summary: Get Scheduled Payment Operations
      description: |
        Retrieve the list of executed payments for a given Scheduled Payment order.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getScheduledPaymentOperations
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - name: scheduledPaymentId
          in: path
          description: The unique identifier of the Scheduled Payment order.
          required: true
          schema:
            type: string
            example: "12345"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  cursor:
                    type: object
                    properties:
                      prev:
                        type: string
                        nullable: true
                        description: |
                          Pointer value for previous page. Set to `null` when on the first page.
                        example: "356a192b7913b04c54574d18c28d46e6395428ab"
                      current:
                        type: string
                        nullable: true
                        description: |
                          Pointer for the current page.
                        example: "da4b9237bacccdf19c0760cab7aec4a8359010b0"
                      next:
                        type: string
                        nullable: true
                        description: |
                          Pointer value for next page. Set to `null` when on the first page.
                        example: "da4b9237bacccdf19c0760cab7aec4a8359010b0"
                  payments:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          example: "2024-02-27 08:15:51"
                        amount:
                          type: string
                          format: float
                          example: "24.99"
                        currency: 
                          type: string
                          format: ISO-4217
                          example: "EUR"
                        endToEndId:
                          type: string
                        label: 
                          type: string
                          example: "School fees"
                        status:
                          type: string
                        paymentId:
                          type: integer
                        errorCode: 
                          type: string
                        errorMessage:
                          type: string
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
          - read_only
          - read_write
  /v1/topups/cards/authorizations:
    post:
      summary: Create Authorization
      description: | 
        Create an authorization to make a card topup payin within 7 days. The card must be [tokenized](/guide/acquiring/card-tokenization.html) first.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`authorization.create`](/guide/acquiring/events.html#authorization-create) |
      operationId: postAcqAuth
      tags:
        - Acquiring (Card Topups)
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizationRequest'
      responses:
        '200':
          description: An authorization has been created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authorization'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - read_write
  /v1/topups/cards/authorizations/{authorizationUuid}:
    get:
      summary: Get Authorization
      description: |
        Retrieve an authorization from the system.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_only` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | N/A |
      operationId: getAcqAuth
      tags:
        - Acquiring (Card Topups)
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - in: path
          name: authorizationUuid
          required: true
          description: Universally unique identifier (UUID) of the authorization
          schema:
            type: string
            format: uuid
            example: "9ea4c7f6-50a2-4679-8634-dfe42f03cbdc"
      responses:
        '200':
          description: Authorization returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authorization'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - read_write
            - read_only
    delete:
      summary: Delete Authorization
      description: |
        Cancels an authorization, making the funds unavailable for capture.

        |     |     | 
        | --- | --- |
        | **[Scopes](/guide/api-basics/authentication.html#scopes-permissions)** | `read_write` |
        | **[SCA](/guide/strong-customer-authentication/introduction.html)** | N/A |
        | **[Webhook](/guide/webhooks/introduction.html)** | [`authorization.cancel`](/guide/acquiring/events.html#authorization-cancel) |
      operationId: deleteAcqAuth
      tags:
        - Acquiring (Card Topups)
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - in: path
          name: authorizationUuid
          required: true
          description: Universally unique identifier (UUID) of the authorization
          schema:
            type: string
            format: uuid
            example: "9ea4c7f6-50a2-4679-8634-dfe42f03cbdc"
      responses:
        '200':
          description: Authorization returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationDeleteResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - read_write
  /v1/topups/cards/authorizations/{authorizationUuid}/payins:
    post:
      summary: Create Payin from Authorization
      description: Create a payin from an authorization. The amount must be ≤ to the authorization amount. [Learn more](/guide/acquiring/preauthorized.html#advanced-capture).
      operationId: postAcqAuthPayin
      tags:
        - Acquiring (Card Topups)
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - in: path
          name: authorizationUuid
          required: true
          description: Universally unique identifier (UUID) of the authorization
          schema:
            type: string
            format: uuid
            example: "9ea4c7f6-50a2-4679-8634-dfe42f03cbdc"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                  format: float
                  description: The amount of the payin. Must be ≤ to the authorization amount.
                currency: 
                  type: string
                  description: |
                    The currency of the operation. Format: ISO-4217.
      responses:
        '200':
          description: Payin returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaptureResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - read_write
    get:
      summary: Get Authorization Payins
      description: List payins created from a given authorization.
      operationId: getAcqAuthPayins
      tags:
        - Acquiring (Card Topups)
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - in: path
          name: authorizationUuid
          required: true
          description: Universally unique identifier (UUID) of the authorization
          schema:
            type: string
            example: "9ea4c7f6-50a2-4679-8634-dfe42f03cbdc"
        - in: query
          name: exclusiveStartKey
          description: The exclusive start key returned by a previous call
          schema:
            type: string
      responses:
        '200':
          description: List of Payins is returned
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AcquiringPayin'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - read_write
            - read_only

  /simulation/topups/cards/notification/authorizations:
    post:
      summary: Simulate HiPay authorization notification
      description: |
        Mocks an HiPay authorization notification provided the minimal set of parameters to generate a refund notification.
      operationId: acquiringv2-topup-cards-simulation-notification-authorization
      tags:
        - Acquiring (Simulation)
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationSimulationAuthorizations'
      responses:
        '200':
          description: Authorization notification successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationSimulationAuthorizationResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - admin
  /simulation/topups/cards/notification/payins:
    post:
      summary: Simulate HiPay payin notification
      description: |
        Mocks an HiPay payin notification providing the minimal set of parameters to generate a payin notification.
      operationId: acquiringv2-topup-cards-simulation-notification-payins
      tags:
        - Acquiring (Simulation)
      #parameters:
       # - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/NotificationSimulationPayins'
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationSimulationPayins'
      responses:
        '200':
          description: Payin notification successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationSimulationPayinResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - admin
  /simulation/topups/cards/notification/refunds:
    post:
      summary: Simulate HiPay refund notification
      description: |
        Mocks an HiPay refund notification providing the minimal set of parameters to generate a refund notification.
      operationId: acquiringv2-topup-cards-simulation-notification-refunds
      tags:
        - Acquiring (Simulation)
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationSimulationRefunds'
      responses:
        '200':
          description: Refund notification successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationSimulationRefundResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - admin
  /simulation/topups/cards/notification/chargebacks:
    post:
      summary: Simulate HiPay chargeback notification
      description: |
        Mocks an HiPay chargeback notification providing the minimal set of parameters to generate a chargeback notification.
      operationId: acquiringv2-topup-cards-simulation-notification-chargebacks
      tags:
        - Acquiring (Simulation)
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationSimulationChargebacks'
      responses:
        '200':
          description: Chargeback notification successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationSimulationChargebackResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - admin
  /v1/topups/cards/refunds/{refundUuid}:
    get:
      summary: Get Refund
      description: Retrieve a card acquiring refund from the system.
      operationId: acquiringv2-topup-cards-refunds-get
      tags:
        - Acquiring (Card Topups)
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - in: path
          name: refundUuid
          required: true
          description: Universally unique identifier (UUID) of the refund
          schema:
            type: string
            format: uuid
            example: "9ea4c7f6-50a2-4679-8634-dfe42f03cbdc"
      responses:
        '200':
          description: Refund returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - read_write
            - read_only
  /v1/topups/cards/refunds:
    post:
      summary: Create Refund
      description: Create a new card topup refund.
      operationId: acquiringv2-topup-cards-refunds-post
      tags:
        - Acquiring (Card Topups)
      #parameters:
        #- $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundRequest'
      responses:
        '200':
          description: Payin successfully refunded. A list of refunds is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - read_write
  /v1/topups/cards/chargebacks/{chargebackUuid}:
    get:
      summary: Get Chargeback
      description: Retrieve a card acquiring a chargeback from the system.
      operationId: acquiringv2-topup-cards-chargebacks-get
      tags:
        - Acquiring (Card Topups)
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - in: path
          name: chargebackUuid
          required: true
          description: Universally unique identifier (UUID) of the chargeback
          schema:
            type: string
            format: uuid
            example: "9ea4c7f6-50a2-4679-8634-dfe42f03cbdc"
      responses:
        '200':
          description: Chargeback returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargebacksResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - read_write
            - read_only
  /v1/topups/cards/users/{userId}/topupCards:
    post:
      summary: Create Topup Card
      description: |
        Create a new topup card. The card must have been previously tokenized.
      operationId: postTopupCard
      tags:
        - Acquiring (Card Topups)
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TopupCardRequest'
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - in: path
          name: userId
          required: true
          description: The owning user identifier
          schema:
            type: string
            example: "12345"
      responses:
        '200':
          description: Topup card was created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopupCards'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - read_write
    get:
      summary: Search Topup Cards
      description: Get topup cards.
      operationId: getTopupCards
      tags:
        - Acquiring (Card Topups)
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - in: path
          name: userId
          required: true
          description: The owning user identifier
          schema:
            type: string
            example: "12345"
      responses:
        '200':
          description: A topup cards details search response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopupCards'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - read_write
            - read_only
  /v1/topups/cards/users/{userId}/topupCards/{topupCardId}:
    get:
      summary: Get Topup Card
      description: Retrieve the details of a Topup Card.
      operationId: getTopupCard
      tags:
        - Acquiring (Card Topups)
      parameters:
       # - $ref: '#/components/parameters/Authorization'
        - in: path
          name: userId
          required: true
          description: The owning user identifier
          schema:
            type: string
            example: "12345"
        - in: path
          name: topupCardId
          required: true
          description: The identifier of the topup card to be retrieved
          schema:
            type: string
            example: "12345"
      responses:
        '200':
          description: A topup card details search response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopupCards'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - read_write
            - read_only
    delete:
      summary: Cancel Topup Card
      description: Change topup card status to CANCELED.
      operationId: deleteTopupCard
      tags:
        - Acquiring (Card Topups)
      parameters:
        #- $ref: '#/components/parameters/Authorization'
        - in: path
          name: userId
          required: true
          description: The owning user identifier
          schema:
            type: string
            example: "12345"
        - in: path
          name: topupCardId
          required: true
          description: The identifier of the topup card to be canceled
          schema:
            type: string
            example: "12345"
      responses:
        '200':
          description: Topup card was canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopupCards'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - read_write
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      description: | 
        The Treezor API is secured by a JWT provided by Treezor, with OAuth2 client credentials flow.
        The token can be used in the `Authorization` header as `Bearer <token>`.
      flows:
        clientCredentials:
          tokenUrl: https://your-company-name.sandbox.treezor.co/oauth/token
          refreshUrl: https://your-company-name.sandbox.treezor.co/oauth/token
          scopes:
            read_only: Access for GET endpoints (except legal, admin) 
            read_write: Access for PUT|POST|DELETE endpoints (except legal, admin)
            admin: Access for API configuration-related endpoints
            legal: Access for sensitive endpoints (e.g., KYC, users, documents)
  # parameters: 
    # Authorization:
    #   name: Authorization
    #   in: header
    #   required: true
    #   description: |
    #     Authorization header that contains a Bearer JWT. <br> See the [Authentication](/guide/api-basics/authentication.html) article for more information.
    #   schema:
    #     type: string
    #     example: 'Bearer YOUR_SECRET_TOKEN'

  responses:
    BadRequestError:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DefaultError'
    NotAllowedError:
      description: Method Not Allowed
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      example: invalid_request
                    code:
                      type: string
                      example: resource_not_found_error
                    message:
                      type: string
                      example: The target resource doesn't support this method.
                    docUrl:
                      type: string
                      example: https://docs.treezor.com/guide/api-basics/response-codes.html 
                    requestId:
                      type: string
                      format: uuid
                      description: | 
                        The unique identifier of the error. This field isn't always displayed.
                      example: "293f2ab1-77a7-42d7-8b3f-de4db3fe9d7d"
    UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DefaultError'
    NotFoundError:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DefaultError'
    ForbiddenError:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DefaultError'
    InternalServerError:
      description: Internal Server Error
      content: 
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      example: "unexpected_internal_server_error"
                    code:
                      type: string
                      example: "unexpected_error"
                    message:
                      type: string
                      example: "internal server error"
                    docUrl:
                      type: string
                      example: "https://docs.treezor.com/guide/api-basics/response-codes.html"
                    requestId:
                      type: string
                      format: uuid
                      example: "293f2ab1-77a7-42d7-8b3f-de4db3fe9d7d"                 
        
    DigitalizedCardsInternalError:
      description: Internal error.
      content: 
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      example: "unexpected_internal_server_error"
                    code:
                      type: string
                      example: "unexpected_error"
                    message:
                      type: string
                      example: ""
                    docUrl:
                      type: string
                      example: "https://docs.treezor.com/guide/api-basics/response-codes.html"
                    requestId:
                      type: string
                      format: uuid
                      example: "293f2ab1-77a7-42d7-8b3f-de4db3fe9d7d"
    DigitalizedCardsBadRequest:
      description: Invalid or missing input (or invalid card status)
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      example: "invalid_request"
                    code:
                      type: string
                      example: "invalid_parameter_in_request"
                    message:
                      type: string
                      description: Error description for human use. Content subject to change without notice.
                    docUrl:
                      type: string
                      example: https://docs.treezor.com/guide/api-basics/response-codes.html
                    requestId:
                      type: string
                      format: uuid
                      example: "293f2ab1-77a7-42d7-8b3f-de4db3fe9d7d"
    DigitalizedCardsUnauthorizedError:
      description: User not authorized to make this request
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      example: "invalid_client"
                    code:
                      type: string
                      example: "authorization_error"
                    message:
                      type: string
                      description: Error description for human use. Content subject to change without notice.
                    docUrl:
                      type: string
                      example: https://docs.treezor.com/guide/api-basics/response-codes.html
                    requestId:
                      type: string
                      format: uuid
                      example: "293f2ab1-77a7-42d7-8b3f-de4db3fe9d7d"
    DigitalizedCardsNotFound:
      description: Digitized Card does not exist
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      example: "not_found"
                    code:
                      type: string
                      example: "resource_not_found_error"
                    message:
                      type: string
                      description: Error description for human use. Content subject to change without notice.
                    docUrl:
                      type: string
                      example: https://docs.treezor.com/guide/api-basics/response-codes.html
                    requestId:
                      type: string
                      format: uuid
                      example: "293f2ab1-77a7-42d7-8b3f-de4db3fe9d7d"
  schemas:
    DefaultError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                example: invalid_request
              code:
                type: string
                example: resource_not_found_error
              message:
                type: string
                example: The userId field is required
              docUrl:
                type: string
                example: https://docs.treezor.com/guide/api-basics/response-codes.html 
              requestId:
                type: string
                format: uuid
                description: | 
                  The unique identifier of the error. This field isn't always displayed.
                example: "293f2ab1-77a7-42d7-8b3f-de4db3fe9d7d"
    
    DigitizedCardResponse:
      type: object
      properties:
        cardId:
          type: string
          description: The unique identifier of the card.
          example: "12345"
        createdDate:
          type: string
          description: |
            The date and time at which the digitized card was created.

            Format: `YYYY-MM-DD HH:mm:ss`
          example: "2025-02-19 14:30:45"
        id:
          type: string
          description: The unique identifier of the digitized card.
          example: "1234567"
        modifiedDate:
          type: string
          description: |
            The date and time at which the digitized card was last updated.

            Format: `YYYY-MM-DD HH:mm:ss`
          example: "2025-02-19 14:30:45"
        status:
          type: string
          description: |
            The status of the digitized card. May be one of the following.
            
            |  | Status | Description |
            | :---: | ------ | ----- |
            | `A` | Active | Initial status of your DPAN upon card digitization. |
            | `I` | Inactive | This is for Visa Scheme only. |
            | `S` | Suspended | DPAN suspended (card stolen, lost, or declared fraudulent). |
            | `X` | Deactivated | DPAN deactivated (e.g., card expired). |
          enum: ["A","I","S","X"]
    ListDigitalizedCardResponse:
      type: array
      items:
        $ref: '#/components/schemas/GetDigitalizedCardResponse'
    GetDigitalizedCardResponse:
      type: object
      properties:
        activationMethod:
          type: string
          description: The method used to activate the digitized card
          enum:
            - TEXT_TO_CARDHOLDER_NUMBER
            - EMAIL_TO_CARDHOLDER_ADDRESS
            - CARDHOLDER_TO_CALL_AUTOMATED_NUMBER
            - CARDHOLDER_TO_CALL_MANNED_NUMBER
            - CARDHOLDER_TO_VISIT_WEBSITE
            - CARDHOLDER_TO_USE_MOBILE_APP
            - ISSUER_TO_CALL_CARDHOLDER_NUMBER
            - UNKNOWN
        cardDigitalizationExternalId:
          type: string
          description: Digitalized card's external identifier.
          example: "12345"
        cardId:
          type: string
          description: The unique identifier of the virtual or physical card.
          example: "12345"
        createdDate:
          type: string
          description: |
            The date and time at which the digitized card was created.

            Format: `YYYY-MM-DD HH:mm:ss`
          example: "2025-02-19 14:30:45"
        deviceId:
          type: string
          description: The identifier of the device linked to the digitized card.
          example: "987654"
        deviceName:
          type: string
          description: The name of the device linked to the digitized card.
          example: "iPhone de Chris"
        deviceType:
          type: string
          description: |
            Type of the device, can be one of the following. 

            | Value | Description |
            |:---:|---|
            | `A` | Clothing or apparel |
            | `B` | Media or Gaming device, e.g., Xbox, TV, set-top box |
            | `C` | Card |
            | `D` | Domestic application, e.g., fridge, washing machine |
            | `F` | Fob or key-fob |
            | `G` | Mobile tag, case, or sleeve |
            | `H` | Fashion accessory, e.g., purse, glasses |
            | `J` | Jewelry, e.g., necklace, rings, bracelets |
            | `M` | Mobile phone |
            | `P` | Personal computer or laptop |
            | `R` | Wristband (no further detail.). Possibly includes rings too |
            | `S` | Sticker |
            | `T` | Tablet |
            | `U` | Unknown |
            | `V` | Vehicle |
            | `W` | Watch |
            | `X` | Mobile phone or tablet (sender unclear) |
          enum: [ "A","B","C","D","F","G","H","J","M","P","R","S","T","U","V","W","X"]
          example: "C"
        expirationDate:
          type: string
          description: |
            The date and time at which the digitized card was expired.

            Format: `YYYY-MM-DD HH:mm:ss`
          example: "2025-02-19 14:30:45"
        id:
          type: string
          description: The unique identifier of the digitized card
          example: "1234567"
        merchantName:
          type: string
          description: |
            Name of the merchant at the origin of the digitization, 
            mainly used when the tokenRequestor is *MRCHTOKEN*.
          example: "Fnac"
        modifiedDate:
          type: string
          description: |
            The date and time at which the digitized was modified.

            Format: `YYYY-MM-DD HH:mm:ss`
          example: "2025-02-19 14:30:45"
        status:
          type: string
          description: |
            The status of the digitized card. May be one of the following. 

            |  | Status | Description |
            | :---: | ------ | ----- |
            | `A` | Active | Initial status of your DPAN upon card digitization. |
            | `I` | Inactive | This is for Visa Scheme only. |
            | `S` | Suspended | DPAN suspended (card stolen, lost, or declared fraudulent). |
            | `X` | Deactivated | DPAN deactivated (e.g., card expired). |
          enum: ["A","I","S","X"]
          example: "A"
        tokenRequestor:
          type: string
          description: |
            The name of the wallet provider.

            While most of the time the only values you'll get are `APPLE`, `GOOGLE`, `MERCHTOKEN`, and `SAMSUNG`, some specific integrations may return other token requestors.
          enum: [ADYENAMAZON,ANDROID,APPLE,ASIA,CHUNGHWA,FITBIT,GARMIN,GOOGLE,LGPAY,MASTERPASS,MICROSOFT,MRCHTOKEN,MTBLANC,PAYNETPHYR,RELIANCE,SAMA,SAMSUNG,SECURECO,STOCARD,VISA_DCA,VISACKOUT,WORLDPAY,OTHER]
          example:  "APPLE"
        tokenServiceProvider:
          type: string
          description: tokenServiceProvider
          enum: [Mastercard]
          example: "Mastercard"
        tokenUniqueReference:
          type: string
          description: The identifier stored by the token service provider (MDES or VTS).

    AuthorizationDeleteResponse:
      type: object
      properties:
        operation:
          type: string
          description: This value will always be 'cancel'.
        profile:
          type: string
          description: HiPay merchant identifier (mid)
        authorizationCode:
          type: string
          description: HiPay authorization code linked to the authorization
        transactionReference:
          type: string
          description: The reference of the transaction
        dateCreated:
          type: string
          description: The creation date of the authorization
        dateUpdated:
          type: string
          description: The last update date of the authorization
        dateAuthorized:
          type: string
          description: The authorized date of the authorization
        status:
          type: string
          description: Transaction status returned by HiPay
        message:
          type: string
          description: Message returned by HiPay
        authorizedAmount:
          type: string
          description: Authorized amount
        capturedAmount:
          type: string
          description: Captured amount
        refundedAmount:
          type: string
          description: Refunded amount
        decimals:
          type: string
          description: |
            The number of digits after the decimal point of the transaction
            amount
        currency:
          type: string
          description: |-
            Base currency for this authorization

            This three-character currency code must comply with ISO-4217
    AcquiringPayin:
      type: object
      properties:
        payinId:
          type: string
          description: The universally unique identifier (UUID) of the payin
        userId:
          type: string
          description: The unique identifier of the User requesting the payin
        walletId:
          type: string
          description: The unique identifier of the wallet to be credited
        userFirstName:
          type: string
          description: The firstname of the user
        walletEventName:
          type: string
          description: The name of the wallet
        walletAlias:
          type: string
          description: Short URL wallet name
        userLastName:
          type: string
          description: The lastname of the user
        messageToUser:
          type: string
          description: Message to send to user owning the wallet
        payinStatus:
          type: string
          description: |
            The status of the payin. 
          enum:
            - CANCELED
            - PENDING
            - VALIDATED
        paymentMethodId:
          type: string
          description: Treezor internal payment method identifier. `25` for card top-ups.
        amount:
          type: number
          format: float
          description: The amount of the payin.
        currency:
          type: string
          description: |
            Base currency for the payin.

            This 3-character currency code must comply with ISO-4217
        createdDate:
          type: string
          description: The creation date of the payin
        codeStatus:
          type: string
          description: |
            Treezor status code mixed with HiPay notification status code: 150000 + (status code). 
            
            Example: For a successful payin, the HiPay notification status code will be 118. The codeStatus will be 150118
        informationStatus:
          type: string
          description: |
            Informational message related to the HiPay status code. This message is destined to the user
        refundAmount:
          type: number
          format: float
          description: Refunded amount
        createdIp:
          type: string
          description: The IP address of the end user making a top-up
        profile:
          type: string
          description: Your HiPay Merchant ID. 
        payinTag:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always empty
        payinDate:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always 0000-00-00
        cartId:
          type: number
          deprecated: true
        subtotalItems:
          nullable: true
          type: string
          default: 'null'
          deprecated: true
        subtotalServices:
          nullable: true
          type: string
          default: 'null'
          deprecated: true
        subtotalTax:
          nullable: true
          type: string
          default: 'null'
          deprecated: true
        distributorFee:
          nullable: true
          type: string
          default: 'null'
          deprecated: true
        paymentHtml:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        paymentLanguage:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        paymentPostUrl:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        paymentPostDataUrl:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        paymentAcceptedUrl:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        paymentWaitingUrl:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        paymentCanceledUrl:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        paymentRefusedUrl:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        paymentExceptionUrl:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        ibanFullname:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        ibanId:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        ibanBic:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        ibanTxEndToEndId:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        ibanTxId:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        forwardUrl:
          nullable: true
          type: string
          default: 'null'
          description: |
            For some payment methods, the end user must be redirected to this URL in order for him to enter additional payment information.
        mandateId:
          nullable: true
          type: number
          default: 0
          description: This field is not used, always 0
        creditorName:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        creditorAddressLine:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        creditorCountry:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        creditorIban:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        creditorBIC:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        virtualIbanId:
          nullable: true
          type: number
          default: null
          description: This field is not used, always null
        virtualIbanReference:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        additionalData:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always empty
    RefundResponse:
      type: object
      properties:
        payinrefundId:
          type: string
          description: The universally unique identifier (UUID) of the refund.
        payinrefundTag:
          type: string
          nullable: true
          default: 'null'
        payinrefundStatus:
          type: string
          description: |
            Status of the refund.
          enum:
            - ACCEPTED
            - CANCELED
            - PENDING
            - VALIDATED
        walletId:
          type: string
          description: Identifier of the wallet to be debited
        payinId:
          type: string
          description: The universally unique identifier (UUID) of the payin
        amount:
          type: number
          format: float
          description: The amount to be refunded
        currency:
          type: string
          description: |
            Base currency for the refund.

            This three-character currency code must comply with ISO-4217
        createdDate:
          type: string
          description: The creation date of the refund
        modifiedDate:
          type: string
          description: The last updated date of the refund
        payinrefundDate:
          type: string
          description: The date of the refund
        profile:
          type: string
          description: Your HiPay Merchant ID. 
    RefundsResponse:
      type: object
      properties:
        payinRefunds:
          type: array
          items:
            $ref: '#/components/schemas/RefundResponse'
    ChargebackResponse:
      type: object
      properties:
        chargebackId:
          type: string
          description: The universally unique identifier (UUID) of the chargeback
        chargebackTag:
          type: string
          nullable: true
          default: 'null'
        chargebackStatus:
          type: string
          description: The status of the chargeback.
        chargebackDate:
          type: string
          description: The date of the chargeback
        walletId:
          type: string
          description: The identifier of the wallet to be debited
        amount:
          type: number
          format: float
          description: The amount to be chargebacked
        currency:
          type: string
          description: |
            Base currency for the chargeback.

            This 3-character currency code must comply with ISO-4217
        createdDate:
          type: string
          description: | 
            The date and time at which the Chargeback was created. Format: `YYYY-MM-DD HH:mm:ss`
          example: "2022-01-26 14:32:17"
        modifiedDate:
          type: string
          description: | 
            The date and time at which the Chargeback was last updated. Format: `YYYY-MM-DD HH:mm:ss`
          example: "2022-01-26 14:32:17"
        profile:
          type: string
          description: HiPay merchant identifier (mid)
    ChargebacksResponse:
      type: object
      properties:
        chargebacks:
          type: array
          items:
            $ref: '#/components/schemas/ChargebackResponse'
    NotificationSimulationPayins:
      type: object
      properties:
        userId:
          type: string
          description: |
            Identifier of the user on behalf of which the simulated payin should be executed
        walletId:
          type: string
          description: Identifier of the wallet to be credited
        amount:
          type: number
          format: float
          description: Payin amount
        currency:
          type: string
          description: |
            Base currency for this payin

            This 3-character currency code must comply with ISO-4217
        status:
          type: integer
          description: The status code of the simulated notification
        transactionReference:
          type: string
          description: The reference of the transaction
        cardPaymentMethod:
          type: object
          description: Payment card used during payin
          properties:
            brand:
              type: string
            cardExpiryMonth:
              type: string
            cardExpiryYear:
              type: string
            cardHolder:
              type: string
            country:
              type: string
            issuer:
              type: string
            maskedPan:
              type: string
            token:
              type: string
        profile:
          type: string
          description: |
            HiPay merchant identifier (mid) to be used for the operation.
            Required if the client has multiple merchant identifiers associated.
            If only one mid is associated, then that one is used for the operation.
      required:
        - walletId
        - amount
        - currency
    NotificationSimulationRefunds:
      type: object
      properties:
        userId:
          type: string
          description: |
            The unique identifier of the user on behalf of which the simulated refund should be executed.
        walletId:
          type: string
          description: The unique identifier of the wallet to be credited.
        amount:
          type: number
          format: float
          description: The amount of the refund.
          example: 26.92
        currency:
          type: string
          description: |
            Base currency for this refund

            This 3-character currency code must comply with ISO-4217
        status:
          type: integer
          description: The status code of the simulated notification.
        transactionReference:
          type: string
          description: The reference of the transaction.
        payinId:
          type: string
          format: uuid
          description: The unique identifier (UUID) of the payin.
      required:
        - payinId
    NotificationSimulationChargebacks:
      type: object
      properties:
        transactionReference:
          type: string
          description: The reference of the transaction.
      required:
        - transactionReference
    NotificationSimulationAuthorizations:
      type: object
      properties:
        amount:
          type: number
          format: float
          description: The amount of the authorization.
          example: 26.92
        cardPaymentMethod:
          type: object
          description: Payment card used during authorization
          properties:
            brand:
              type: string
            cardExpiryMonth:
              type: string
            cardExpiryYear:
              type: string
            cardHolder:
              type: string
            country:
              type: string
            issuer:
              type: string
            maskedPan:
              type: string
            token:
              type: string
        currency:
          type: string
          description: |
            Base currency for this authorization

            This 3-character currency code must comply with ISO-4217
        status:
          type: integer
          description: The status code of the simulated notification
        transactionReference:
          type: string
          description: The reference of the transaction
        userId:
          type: string
          description: |
            Identifier of the user on behalf of which the simulated
            authorization should be executed
        walletId:
          type: string
          description: Identifier of the wallet to be credited
        profile:
          type: string
          description: |
            HiPay merchant identifier (mid) to be used for the operation.
            Required if the client has multiple merchant identifiers associated.
            If only one mid is associated, then that one is used for the operation.
      required:
        - amount
        - currency
        - walletId
    RefundRequest:
      type: object
      properties:
        payinUid:
          type: string
          format: uuid
          description: The unique identifier (UUID) of the payin.
        amount:
          type: number
          format: float
          description: The amount of the refund.
          example: 12.89
        currency:
          type: string
          description: |
            Base currency for this refund

            This 3-character currency code must comply with ISO-4217
        profile:
          type: string
          description: |
            HiPay merchant identifier (mid) to be used for the operation.
            Required if the client has multiple merchant identifiers associated.
            If only one mid is associated, then that one is used for the operation. Mandatory for legacy payins refunds
      required:
        - payinUid
    TopupCardRequest:
      type: object
      properties:
        token:
          type: string
          description: |
            The Card token generated by HiPay. Learn more in the [Tokenization](/guide/acquiring/card-tokenization.html) article.
        profile:
          type: string
          description: Your HiPay Merchant ID. Required if you have multiple MIDs, otherwise empty.
      required:
        - token
    CaptureResponse:
      type: object
      properties:
        operation:
          type: string
          description: This value will always be 'capture'.
        profile:
          type: string
          description: HiPay merchant identifier (mid), also known as profile
        authorizationCode:
          type: string
          description: HiPay authorization code linked to the payin
        transactionReference:
          type: string
          description: The reference of the transaction
        dateCreated:
          type: string
          description: The creation date of the payin
        dateUpdated:
          type: string
          description: The last update date of the payin
        dateAuthorized:
          type: string
          description: The authorized date of the payin
        status:
          type: string
          description: Transaction status returned by HiPay
        message:
          type: string
          description: Message returned by HiPay
        authorizedAmount:
          type: string
          description: Authorized amount
        capturedAmount:
          type: string
          description: Captured amount
        refundedAmount:
          type: string
          description: Refunded amount
        decimals:
          type: string
          description: |
            The number of digits after the decimal point of the transaction amount.
        currency:
          type: string
          description: |
            Base currency for this payin

            This 3-character currency code must comply with ISO-4217
    AuthorizationRequest:
      type: object
      properties:
        amount:
          type: number
          description: The amount of the operation.
        currency:
          type: string
          format: ISO-4217
          description: |
            The currency of the operation. Format: ISO-4217.
        walletId:
          type: string
          description: The unique identifier of the wallet to be credited.
        userId:
          type: string
          description: The unique identifier of the user requesting the operation.
        topupCardId:
          type: string
          description: The unique identifier for the user's Topup Card.
        acceptUrl:
          type: string
          description: |
            The URL to return the end user to once the payment process is completed successfully.
        declineUrl:
          type: string
          description: |
            The URL to return the end user to after the acquirer declines the payment.
        pendingUrl:
          type: string
          description: |
            The URL to return your end user to when the payment request was submitted to the acquirer but response is not yet available.
        exceptionUrl:
          type: string
          description: The URL to return your end user to after a system failure
        cancelUrl:
          type: string
          description: The URL to return your end user to after a system failure
        eci:
          type: string
          description: |
            The ECI indicates the security level at which the payment information is processed between the cardholder and Treezor customer
        authenticationIndicator:
          type: string
          description: |
            If the payment product is a credit or debit card, this parameter indicates if the 3D Secure authentication should be performed for this transaction
        orderId:
          type: string
          minLength: 32
          description: |
            The unique identifier of the order, guaranteeing the uniqueness of the transaction. 
            
            Must be unique and abide by the following rules:
            * Length: min. 32 characters
            * Structure: `<yourCompanyName>_order_<uniqueIdentifier>`
        description:
          type: string
          description: The order short description.
        paymentProduct:
          type: string
          description: |
            The payment method used for the top-up.

            Depending on the payment product, parameters specific to the payment method are required.
        issuerBankId:
          type: string
          description: |
            This parameter is specific to the iDEAL payment product.

            This is the Business Identifier Code (BIC) of the end user issuer bank
        ipaddr:
          type: string
          description: The IP address of the end user making a top-up
        deviceChannel:
          type: integer
          description: |
            This parameter is specific to the PSD2. Channel through which the transaction is being processed
        browserInfo:
          type: object
          properties:
            javaEnabled:
              type: boolean
              description: |
                Represents the ability of the device's browser to run Java, when applicable.
            javascriptEnabled:
              type: boolean
              description: |
                Represents the ability for the client's browser to run JavaScript.
            ipaddr:
              type: string
              description: The IP address of the end user making a top-up.
            httpAccept:
              type: string
              description: |
                This element must include the exact content of the HTTP Accept header, as sent to the Treezor customer from the end user.
            httpUserAgent:
              type: string
              description: |
                This element must include the exact content of the User_Agent HTTP header, as sent to the Treezor customer from the end user.
            language:
              type: string
              description: |
                Value representing the client's browser language as defined in IETF-BCP47.
            colorDepth:
              type: integer
              description: |
                Value representing the depth of the color palette to display an image, in bits/pixel.
              enum: [ 1, 4, 8, 15, 16, 32, 48]
            screenHeight:
              type: integer
              description: Total height of the device screen (in pixels), when applicable.
            screenWidth:
              type: integer
              description: Total width of the end user screen (in pixels).
            timezone:
              type: string
              description: |
                Time difference in minutes between UTC and cardholder's browser local time.
            deviceFingerprint:
              type: string
        profile:
          type: string
          description: |
            Your HiPay Merchant ID. Required if you have multiple MIDs, otherwise empty.
        firstname:
          type: string
          description: The first name of the user.
          example: "Alex"
        lastname:
          type: string
          description: The last name of the user.
          example: "Oak"
        email:
          type: string
          description: The email of the user.
          example: "a.oak@example.com"
        phone:
          type: string
          description: The phone number of the user.
        streetAddress:
          type: string
          description: The residence street name and number of the user.
        city:
          type: string
          description: The residence city of the user.
        zipCode:
          type: string
          description: The residence city zipcode of the user.
        country: 
          type: string
          format: ISO 3166 alpha-2
          description: |
            The residence country of the user.
        cardHolder:
          type: string
          description: The name associated to the card.
          example: "Alex Oak"
      required:
        - orderId
        - description
        - paymentProduct
        - userId
        - walletId
        - amount
        - currency
        - acceptUrl
        - declineUrl
        - pendingUrl
        - exceptionUrl
        - cancelUrl
        - eci
        - authenticationIndicator
        - firstname
        - lastname
        - email
        - phone
        - streetAddress
        - city
        - zipCode
        - country
        - cardHolder
        - browserInfo
        - deviceChannel
    TopupCards:
      type: object
      properties:
        topupCards:
          type: array
          items:
            type: object
            properties:
              topupCardId:
                type: string
                description: The tokenized card universally unique identifier (UUID)
              token:
                type: string
                description: HiPay token of the card
              userId:
                type: string
                description: Treezor user unique identifier
              brand:
                type: string
                description: Brand of the payment method
              maskedPan:
                type: string
                description: Masked card number
              cardHolder:
                type: string
                description: Cardholder name
              cardExpiryMonth:
                type: string
                description: Expiry month of the card
              cardExpiryYear:
                type: string
                description: Expiry year of the card
              issuer:
                type: string
                description: Issuer bank name
              country:
                type: string
                format: ISO 3166-1 alpha-2
                description: |
                  Country code of the bank where the card was issued. This 2-letter country code complies with ISO 3166-1 alpha-2.
                example: "FR"
              domesticNetwork:
                type: string
                description: Card domestic network
              cardType:
                type: string
                description: |
                  The type of the card.
                enum: ["DEBIT", "CREDIT"]
              createdDate:
                type: string
                description: | 
                  The date and time at which the Topup Card was created. Format: `YYYY-MM-DD HH:mm:ss`
                example: "2022-01-26 14:32:17"
              updatedDate:
                type: string
                description: | 
                  The date and time at which the Topup Card was updated. Format: `YYYY-MM-DD HH:mm:ss`
                example: "2022-01-26 14:32:17"
              status:
                type: string
                description: |
                  The status of the TopupCard.
                enum:
                  - CANCELED
                  - VALIDATED
              providerName:
                type: string
                description: The token provider name.
                enum: ["HiPay"]
              profile:
                type: string
                description: Acquisition profile used for operations on this card.
    Authorization:
      type: object
      properties:
        authorizationId:
          type: string
          format: uuid
          description: The unique identifier (UUID) of the authorization.
        userId:
          type: string
          description: The unique identifier of the User requesting the authorization.
        walletId:
          type: string
          description: The unique identifier of the wallet to be credited.
        userFirstname:
          type: string
          description: The firstname of the user.
          example: "Alex"
        userLastname:
          type: string
          description: The lastname of the user.
          example: "Oak"
        walletEventName:
          type: string
          description: The name of the Wallet.
        walletAlias:
          type: string
          deprecated: true
        messageToUser:
          type: string
          description: Message to send to wallet user
        authorizationStatus:
          type: string
          description: |
            The status of the authorization. 
          enum:
            - CANCELED
            - EXPIRED
        paymentMethodId:
          type: string
          description: Treezor internal payment method identifier. `25` for card top-ups.
          example: "25"
        amount:
          type: number
          description: The amount of the authorization.
          example: 26.92
        currency:
          type: string
          format: ISO-4217
          description: |
            Base currency for this authorization

            This 3-character currency code must comply with ISO-4217.
        createdDate:
          type: string
          description: | 
            The date and time at which the Authorization was created. Format: `YYYY-MM-DD HH:mm:ss`
          example: "2022-01-26 14:32:17"
        codeStatus:
          type: string
          description: |
            Treezor status code mixed with HiPay notification status code: `150000` + (status code). 
            
            Example: For a successful payin, the HiPay notification status code will be `118` so the `codeStatus` is `150118`.
          example: "150118"
        informationStatus:
          type: string
          description: Informational message towards the user related to the HiPay status code.
        refundAmount:
          type: number
          description: The amount of the refund.
        profile:
          type: string
          description: Your HiPay Merchant ID. Required if you have multiple MIDs, otherwise empty.
        DbtrIBAN:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        createdIp:
          type: string
          description: IP address of the customer making the top-up
        authorizationTag:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always empty
        authorizationDate:
          type: string
          description: This field is not used, always `0000-00-00`.
        cartId:
          type: number
          deprecated: true
        subtotalItems:
          nullable: true
          type: string
          deprecated: true
        subtotalServices:
          nullable: true
          type: string
          deprecated: true
        subtotalTax:
          nullable: true
          type: string
          deprecated: true
        distributorFee:
          nullable: true
          type: string
          deprecated: true
        paymentHtml:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        paymentLanguage:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        paymentPostUrl:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        paymentPostDataUrl:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        paymentAcceptedUrl:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        paymentWaitingUrl:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        paymentCanceledUrl:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        paymentRefusedUrl:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        paymentExceptionUrl:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        ibanFullname:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        ibanId:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        ibanBic:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        ibanTxEndToEndId:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        ibanTxId:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        forwardUrl:
          nullable: true
          type: string
          default: 'null'
          description: For some payment methods, the end user must be redirected to this URL in order for him to enter additional payment information.
        mandateId:
          nullable: true
          type: string
          description: This field is not used, always 0.
        creditorName:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        creditorAddressLine:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        creditorCountry:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        creditorIban:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        creditorBIC:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        virtualIbanId:
          nullable: true
          type: number
          default: null
          description: This field is not used, always null
        virtualIbanReference:
          nullable: true
          type: string
          default: 'null'
          description: This field is not used, always null
        additionalData:
          nullable: true
          type: string
          default: 'null'
          description: |
            This field can be empty or contain information about an external provider. 
    NotificationSimulationAuthorizationResponse:
      type: object
      properties:
        transactionReference:
          type: string
          description: The reference of the transaction.
        authorizationId:
          type: string
          format: uuid
          description: The unique identifier (UUID) of the authorization.
    NotificationSimulationPayinResponse:
      type: object
      properties:
        transactionReference:
          type: string
          description: The reference of the transaction
        payinId:
          type: string
          format: uuid
          description: The unique identifier (UUID) of the payin.
    NotificationSimulationRefundResponse:
      type: object
      properties:
        transactionReference:
          type: string
          description: The reference of the transaction.
        refundId:
          type: string
          format: uuid
          description: The unique identifier (UUID) of the refund.
    NotificationSimulationChargebackResponse:
      type: object
      properties:
        transactionReference:
          type: string
          description: The reference of the transaction being chargebacked.
        chargebackId:
          type: string
          format: uuid
          description: The unique identifier (UUID) of the chargeback.
    BeneficiaryObject:
      type: object
      properties:
        beneficiaries:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                description: |
                  The unique identifier of the Beneficiary.
              tag:
                type: string
                maxLength: 250
                description: |
                    Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
                    
                    Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
              userId:
                type: integer
                description: The unique identifier of the User to which the Beneficiary is attached.
              nickName:
                type: string
                description: |
                  Name chosen by end user to easily recognize the beneficiary.
              name:
                type: string
                maxLength: 70
                description: Beneficiary name, linked to bank account.
              address:
                type: string
                description: Beneficiary address, linked to bank account.
              iban:
                type: string
                description: The encrypted International Bank Account Number (IBAN) of the beneficiary.
                example: "FR763000100794123XXXXXXXX"
              bic:
                type: string
                description: Beneficiary Bank Identifier Code.
                example: "BDFXXXXXX"
              sepaCreditorIdentifier:
                type: string
                description: |
                  Beneficiary [SEPA Creditor Identifier](/guide/overview/glossary.html#sepa-creditor-identifier-sci). Mandatory to validate B2B incoming direct debit, useless otherwise. Between 8 and 35 h.
              sddB2bWhitelist:
                type: array
                description: |
                  Each unique mandate reference, with its frequency type, must be explicitly allowed when doing B2B Direct Debit. 
                  
                  Furthermore, a mandate not used during more than 36 months will be automatically rejected even if in the whitelist.
                items:
                  required:
                    - isRecurrent
                    - uniqueMandateReference
                  type: object
                  properties:
                    uniqueMandateReference:
                      type: string
                      description: |
                        The unique reference that unambiguiously identify a mandate signed between the user and the beneficiary. 
                          
                        See the [Unique Mandate Reference (UMR)](/guide/overview/glossary.html#unique-mandate-reference-umr) article for more information.
                    isRecurrent:
                      type: boolean
                      description: |
                        If mandate is a recurring payment, this field must be true.
                    walletId:
                      type: integer
                      description: |
                        If present, the Direct Debit will be accepted only if the targeted wallet is the wallet with the given walletId. 
                        Without this value, the SDD can target any wallets of the user. 
                        With the value specified, only the explicitly authorized wallet can be targeted by SDD.
              sddCoreBlacklist:
                type: array
                description: |
                  Core Direct Debit are accepted by default. 
                  If a Core mandate is to be refused on reception, it has to be added to this list. 
                  If wild char * (star) is used instead of a UMR, all Direct Debit from this beneficiary will be refused. 
                  Note that the mandate ref entered is case sensitive.
                items:
                  type: string
                  description: |
                    Unique Mandate Reference that unambiguiously identify a mandate signed between the user and the beneficiary.
                    Star character can also be used to reject all Direct debit from the beneficiary.
              usableForSct:
                type: boolean
                description: |
                  Indicated if the beneficiary can be used for SEPA Credit Transfer. This field is a convenient way to filter all beneficiaries for a user that would like to do a Credit Transfer. 

                  Indeed, beneficaries are created automatically when receiving a Core Direct Debit and therefore by looking at the list you won't be able to idnetify which beneficiary to use on SCT.
                default: false
              sddCoreKnownUniqueMandateReference:
                type: array
                items:
                  type: string
                  description: |
                    List of all the unique mandate references received from the beneficiary of Core Direct Debits for given user.
                          
                    See the [Unique Mandate Reference (UMR)](/guide/overview/glossary.html#unique-mandate-reference-umr) article for more information.
              isActive:
                type: boolean
                description: Whether or not the Beneficiary is active.
                default: true
              createdDate:
                type: string
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                description: | 
                  The date and time at which the beneficiary was created. 
                  
                  Format: `YYYY-MM-DD HH:mm:ss`
                example: "2025-01-10 15:49:53"
              modifiedDate:
                type: string
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                description: | 
                  The date and time at which the beneficiary was last updated. 
                  Format: `YYYY-MM-DD HH:mm:ss`
                example: "2025-01-10 15:49:53"
    BeneficiaryValidationObject:
      type: object
      properties:
        beneficiaryValidationId:
          type: string
          format: uuid
          description: The unique identifier of the validation object.
          example: "f8e4a7b2-c1d3-4e5a-8b0f-9c2d1e0a3b5c"
        createdDate:
          type: string
          format: date-time
          description: The date and time at which the beneficiary validation was created.
          example: "2025-08-29T16:52:27Z"
        vop:
          type: object
          properties:
            matchedName:
              type: string
              description: |
                The name declared for the account owner in the banking system. Only populated in case of `CMTC` result.
              nullable: true
              example: "Axel Oak"
            reasonCode:
              type: string
              description: | 
                The reason for which the request to the bank didn't result in a conclusive verification. 
                Only populated in case of `NOAP` result.

                See [Reason codes](/guide/transfers/beneficiaries.html#reason-codes-reasoncode) for the description of each result.
              nullable: true
              enum: [ "9001", "9007", "9008", "9009", "9010" ]
            recurrenceType:
              type: string
              description: |
                Must be set to `scheduled` if you've put in place your own system to schedule payments at a later date (one-time or recurring).
                Scheduled recurrence allow you to use of the same `beneficiaryValidationId` for the subsequent payments.
              enum:
                - default
                - scheduled
            result:
              type: string
              description: |
                Whether the account owner matches the information declared in your systems. 
                
                See [Validation result](/guide/transfers/beneficiaries.html#validation-result-result) to learn more about each result and the message to display to the end user.
              enum: ["MTCH", "NMTC", "CMTC", "NOAP"]
              example: "CMTC"
    InternationalBeneficiaryObject:
      type: object
      properties:
        internationalBeneficiaries:
          type: array
          items:
            type: object
            properties:
              internationalBeneficiaryId:
                type: string
                description: The unique identifier of the International Beneficiary.
                example: "550e8400-e29b-41d4-a716-446655440000"
              userId:
                type: integer
                description: The unique identifier of the User to which the International Beneficiary is attached.
                example: 123456
              nickName:
                type: string
                description: Name chosen by end user to easily recognize the beneficiary.
                example: "A Oak"
              name:
                type: string
                description: International Beneficiary name, linked to bank account.
                example: "Alex Oak"
              type:
                type: string
                description: "Specifies the system used for the transaction."
                example: "ACH"
              currency:
                type: string
                description: "Specifies the target attached to the international beneficiary (target currency)"
                format: ISO 4217
                example: "USD"
              address:
                type: object
                description: The address of the international beneficiary.
                properties:
                  streetName:
                    type: string
                    example: "Liberty Island"
                  buildingNumber:
                    type: string
                    example: "1"
                  city:
                    type: string
                    example: "New York"
                  state:
                    type: string
                    example: "New York"
                  postalCode:
                    type: string
                    example: "10004"
                  country:
                    type: string
                    example: "United States"
              details:
                type: object
                description: |
                  Bank account details. This object varies depending on the target currency and the response of the beneficiary requirements request.
              status:
                type: string
                description: The status of the international beneficiary
                example: "VALIDATED"
              createdDate:
                type: string
                format: date-time
                description: The date and time up at which the international beneficiary was created
                example: "2026-01-22T14:30:00Z"
              modifiedDate:
                type: string
                format: date-time
                description: The date and time up at which the international beneficiary was modified
                example: "2026-02-22T14:30:00Z"
    QuoteObject:
      type: object
      properties:
        quotes:
          type: array
          items:
            type: object
            properties:
              quoteId:
                type: string
                description: The unique identifier of the quote.
                example: "b8a2f1e4-7d3c-4e8a-92b1-5f0c9a6d4211"
              userId:
                type: integer
                description: The unique identifier of the user to which the quote is attached.
                example: 123456
              sourceAmount:
                type: number
                description: |
                  The amount stated in the source currency.
                example: 123.45
              sourceCurrency:
                type: string
                format: ISO 4217
                description: |
                  The source currency. As of today, can only be `EUR`.
                default: "EUR"
              targetAmount:
                type: number
                description: |
                  The amount stated in the target currency.
                example: 121.98
              targetCurrency:
                type: string
                format: ISO 4217
                description: |
                  The currency of the target account. Must be among the [emission supported currencies](/guide/transfers/international.html#supported-currencies).
                example: "USD"
              rate:
                type: string
                description: |
                  The conversion rate for the quote.
              fees:
                type: object
                properties:
                  transferwise:
                    type: integer
                  payIn:
                    type: integer
                  discount:
                    type: integer
                  partner:
                    type: integer
                  total:
                    type: integer
              createdDate:
                type: string
                format: date-time
                description: |
                  The date and time at which the quotation was created. 
                example: "2026-01-23T14:30:00Z"
              estimatedDelivery:
                type: string
                format: date-time
                description: |
                  The date and time at which the international transfer is to arrive in the beneficiary's account.
                example: "2026-01-29T14:30:00Z"
              rateExpirationDate:
                type: string
                format: date-time
                description: The date and time up to which the rate is guaranteed.
                example: "2026-01-23T14:30:00Z"
              expirationDate:
                type: string
                format: date-time
                description: The date and time to which the quotaton expires.
                example: "2026-01-22T15:00:00Z"
    DocumentObject:
      type: object
      properties:
        documents:
          type: array
          items:
            type: object
            properties:
              documentId:
                type: integer
                description: The unique identifier of the Document.
              documentTag:
                type: string
                nullable: true
                maxLength: 250
                description: |
                  Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
                  
                  Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
              clientId:
                type: integer
                description: The unique identifier of the Treezor environment.
              userId: 
                type: integer
                description: The unique identifier of the User the document belongs to.
              userFirstname:
                type: string
                deprecated: true
              userLastname:
                type: string
                deprecated: true
              name: 
                type: string
                description: The name of the document.
                example: "aoak_identity_card.pdf"
              documentStatus:
                type: string
                description: | 
                  The status of the document. See [Document Status](/guide/user-verification/documents.html#status-documentstatus) for more information.
                enum:
                  - CANCELED
                  - PENDING
                  - VALIDATED
              documentTypeId:
                type: integer
                description: | 
                    The id of the type of Document. 
                    
                    See [Document types](/guide/user-verification/documents.html#types-documenttypeid) for the list of values.
                example: 9
              documentType:
                type: string
                description: |
                  The type of the Document.

                  See [Document types](/guide/user-verification/documents.html#types-documenttypeid) for the list of values.
                example: "ID"
              fileName:
                type: string
                example: "1297148.png"
              thumbfileName:
                type: string
                deprecated: true
              createdDate:
                type: string
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                description: | 
                  Date and time at which the document was created.
                  
                  Format: `YYYY-MM-DD HH:mm:ss`
                example: "2025-01-10 15:49:53"
              modifiedDate: 
                type: string
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                description: | 
                  Date and time at which the document was last updated.
                  
                  Format: `YYYY-MM-DD HH:mm:ss`
                example: "2025-01-10 15:49:53"
              codeStatus:
                type: string
                description: |
                  The status code of the document. See [Status](/guide/user-verification/documents.html#status-documentstatus) for more information.
                example: "600009"
                enum:
                  - "600001"
                  - "600002"
                  - "600003"
                  - "600004"
                  - "600005"
                  - "600006"
                  - "600007"
                  - "600008"
                  - "600009"
                  - "600010"
                  - "600011"
                  - "600012"
                  - "600013"
                  - "600014"
                  - "600015"
                  - "600016"
                  - "600017"
              informationStatus:
                type: string
                description: Additional information about the document status, if any.
                nullable: true
              residenceId:
                type: integer
                format: int64
                description: |
                  The unique identifier of the User's [Tax Residence](/guide/users/tax-residence.html). 
                  
                  Only available for `documentTypeId` is `24` or `25`. 
              temporaryUrl: 
                type: string
                deprecated: true
              temporaryUrlThumb:
                type: string
                deprecated: true
    MandateObject:
      type: object
      properties:
        mandates:
          type: array
          items:
            type: object
            properties:
              mandateId:
                type: integer
                description: The unique identifier of the Mandate.
              title:
                type: string
                description: |
                    The title inherited from the User object. Can be one of the following:
                    * `M` – Stands for mister (Mr.)
                    * `MME` – Stands for missus (Mrs.)
                    * `MLLE` – Stands for miss
                    * `MX` – Gender-neutral title
                enum:
                  - M
                  - MME
                  - MLLE
                  - MX
              legalInformations:
                type: string
                example: "Treezor"
              uniqueMandateReference:
                type: string
                description: |
                  The unique reference that unambiguiously identify a mandate signed between the user and the beneficiary. 
                          
                  See the [Unique Mandate Reference (UMR)](/guide/overview/glossary.html#unique-mandate-reference-umr) article for more information.
                example: "79069343D1A80C931FABBC5813E3DB"
              mandateStatus:
                type: string
                description: The status of the mandate.
                enum:
                  - CANCELED
                  - PENDING
                  - VALIDATED
              userId:
                type: integer
                description: The unique identifier of the User.
              debtorName:
                type: string
                description: | 
                  Full name of the debited end user (person or entity).
                  
                  Format: alphanumeric with at least 3 alphabetic characters.
                example: "Alex Oak"
              debtorAddress:
                type: string
                description: The address of the debited end user. 
              debtorCity:
                type: string
                description: City in which the debited end user is domiciled.
              debtorZipCode:
                type: string
                description: Postcode of the city in which the debited end user is domiciled.
              debtorCountry:
                type: string
                format: ISO 3166-1 alpha-2
                description: Country in which the debited end user is domiciled.
                example: "FR"
              debtorIban:
                type: string
                description: IBAN of the debited user.
                example: "FR763000100794123XXXXXXXX"
              debtorBic:
                type: string
                description: The BIC (or SWIFT) of the debited user.
                example: "BDFXXXXXX"
              sequenceType:
                type: string
                description: |
                    Defines whether or not the debtor will be debited multiple times. Can be one of the following:
                    * `one-off` – For a one-time payment.
                    * `recurrent` – For recurring payments.
                enum:
                  - one-off
                  - recurrent
              creditorName:
                type: string
                description: The full name of the creditor.
                example: "Chris Willow"
              sepaCreditorIdentifier:
                type: string
                description:
                  The [SEPA Creditor Identifier](/guide/overview/glossary.html#sepa-creditor-identifier-sci).
                example: FR47XXX001032
              creditorAddress:
                type: string
                description: The address of the creditor.
              creditorCity:
                type: string
                description: The city in which the creditor is domiciled.
              creditorZipCode:
                type: string
                description: The postcode of the city in which the creditor is domiciled.
              creditorCountry:
                type: string
                description: Country in which the creditor is domiciled.
                format: ISO 3166-1 alpha-2
                example: "FR"
              signatureDate:
                type: string
                format: date
                description: |
                  Date on which the Mandate was signed by the end user.

                  Format: `YYYY-MM-DD`
                example: "2020-04-01"
              debtorSignatureIp:
                type: string
              signed:
                type: integer
                description: Whether or not the mandate is signed.
                enum: [0,1]
              debtorIdentificationCode:
                type: string
              debtorReferencePartyName:
                type: string
              debtorReferenceIdentificationCode:
                type: string
              creditorReferencePartyName:
                type: string
              creditorReferenceIdentificationCode:
                type: string
              contractIdentificationNumber:
                type: string
              contractDescription:
                type: string
              isPaper:
                type: boolean
                description: | 
                    Whether the Mandate is a paper-based document, or electronically signed. As of today, should only be set to `true`.
              sddType:
                type: string
                description: |
                  The type of Mandate, which can be:
                  * `core` – To debit individuals (physical persons).
                  * `b2b` – To debit legal entities.
                enum:
                  - b2b
                  - core
              revocationSignatureDate:
                type: string
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                description: |
                  Date and time at which the mandate was revoked (set to `CANCELED`)
                  
                  Format: `YYYY-MM-DD HH:mm:ss`
                example: "2025-01-10 15:49:53"
              createdIp:
                type: string
              createdDate:
                type: string
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                description: |
                  Date and time at which the mandate was created.
                  
                  Format: `YYYY-MM-DD HH:mm:ss`
                example: "2025-01-10 15:49:53"
              modifiedDate:
                type: string
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                description: |
                  Format: `YYYY-MM-DD HH:mm:ss`
                example: "2025-01-10 15:49:53"
              codeStatus:
                type: integer
                enum:
                  - 220001
                  - 220002
                  - 220003
                  - 220004
                  - 220005
                  - 220006
              informationStatus:
                type: string
                description: | 
                  Additional information regarding the `codeStatus`, if any.
                enum:
                  - 'Mandat complété'
                  - 'Mandat signé'
                  - 'Mandat signé et validé'
                  - 'Mandat révoqué par le débité'
                  - 'Mandat révoqué automatiquement'
                  - 'Mandat révoqué par le crédité'
              userIdUltimateCreditor:
                type: integer
    CardObject:
      type: object
      properties:
        cards:
          type: array
          items:
            type: object
            properties:
              cardId:
                type: integer
                description: The unique identifier of the card.
              userId:
                type: integer
                description: The unique identifier of the cardholder.
              walletId:
                type: integer
                description: The unique identifier of the Wallet the card is attached to.
              walletCardtransactionId:
                type: integer
                description: | 
                  The card technical wallet, for Treezor usage only. See [Card Transaction Wallet](/guide/wallets/introduction.html#card-transaction-wallet-type-14-18) for more information.
              mccRestrictionGroupId:
                type: integer
                description: |
                  The merchant category restriction group (`mccRestrictionGroup`) applied to the card.
                nullable: true
              merchantRestrictionGroupId:
                type: integer
                description: |
                  The merchant Id restriction group (`merchantRestrictionGroupId`) applied to the card.
                nullable: true
              countryRestrictionGroupId:
                type: integer
                description: |
                  The country restriction group (`countryRestrictionGroupId`) applied to the card.
                nullable: true
              publicToken:
                type: string
                minLength: 9
                maxLength: 9
                description: |
                  The 9-character long string printed on the Card. It can be used to [activate](/guide/cards/creation.html#activation) the card.
              cardTag:
                type: string
                maxLength: 250
                description: |
                  Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
                    
                  Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
              statusCode:
                type: string
                description: | 
                  The plaintext value of the [Card status](/guide/cards/introduction.html#card-status-statuscode).
                enum:
                  - CUSTOM_LOCK
                  - DESTROYED
                  - EXPIRED
                  - LOCK_INTERNAL
                  - LOCK
                  - LOST
                  - STOLEN
                  - UNLOCK
              isLive:
                type: integer
                description: |
                  Whether the card is active. Set to `1` once activated. See [Activation](/guide/cards/creation.html#activation) for more information.
                enum: [0,1]
              pinTryExceeds:
                type: integer
                description: |
                  Whether the Card is locked because the cardholder entered 3 erroneous PIN codes in a row. Set to `1` when the card is PIN-locked. 
                  
                  See [PIN Unlock](/guide/cards/modification.html#unlock-pin) for more information.
                enum: [0,1]
              maskedPan:
                type: string
                description: |
                  The [Primary Account Number (PAN)](/guide/overview/glossary.html#primary-account-number-pan) of the card, with the middle numbers redacted for safety.
                example: "519872******3333"
              embossedName:
                type: string
                maxLength: 20
                description: | 
                  The cardholder name embossed on the card. See the [embossed name](/guide/cards/creation.html#embossed-name-embossedname) article for more information.
                example: "ALEX OAK"
              expiryDate:
                type: string
                description: | 
                  The date on which the card expires. 
                  The [`card.expiryAlert`](/guide/cards/events.html#structure-of-a-card-expiryalert) webhook is sent a month before the `expiryDate` for you to anticipate [Renewal](/guide/cards/renewal.html).
                  
                  Format: `YYYY-MM-DD`
                example: "2029-07-04"
              CVV:
                type: string
                description: | 
                  The verification code of the card. This field is to be deprecated and hence may return a value of `000`. 

                  You may retrieve the card CVV by using the [`/v1/cardimages`](/api-reference/api-endpoints.html#tag/Cards/getCardImage) request or by migrating to the [PCI DSS-compliant services](/guide/cards/pci-dss.html).
              startDate:
                type: string
                format: date
                description: The date on which the card was activated.
                example: "2024-07-04"
              endDate:
                type: string
                format: date
                description: The date on which the card reaches a final cardStatus (e.g., `DESTROYED`, `EXPIRED`).
                example: "2029-07-04"
              countryCode:
                type: string
                format: ISO 3166-1 alpha-2
                description: Inherited from the cardholder's country.
                example: "FR"
              currencyCode:
                type: string
                format: ISO 4217
                description: The currency of the card, in the [ISO 4217](/guide/api-basics/data-format.html#currencies) format.
                example: "EUR"
              lang:
                type: string
                deprecated: true
                nullable: true
              deliveryTitle:
                type: string
                description: |
                  The title inherited from the User object (cardholder or parent depending on the `sendToParent` value).
                  
                  Can be one of the following:
                  * `M` – Stands for mister (Mr.)
                  * `MME` – Stands for missus (Mrs.)
                  * `MLLE` – Stands for miss
                  * `MX` – Gender-neutral title
                example: "MX"
                enum:
                  - M
                  - MME
                  - MLLE
                  - MX
              deliveryLastname:
                type: string
                maxLength: 20
                description: |
                  The `lastname` (for physical users) or the `legalName` (for legal entities) inherited from the User object (cardholder or parent depending on the `sendToParent` value). This value is truncated at 20 characters.
                example: "Oak"
              deliveryFirstname:
                type: string
                maxLength: 20
                description: |
                  The first name of the user inherited from the User object (cardholder or parent depending on the `sendToParent` value). This value is truncated at 20 characters.
                example: "Morgan"
              deliveryAddress1:
                type: string
                maxLength: 50
                description: |
                  The postal address (main) inherited from the User object (cardholder or parent depending on the `sendToParent` value). 
                  
                  This value cannot contain carriage return and is truncated at 50 characters. We advise you abide by the [mail carrier limitations](/guide/api-basics/data-format.html#addresses).
              deliveryAddress2:
                type: string
                maxLength: 50
                description: |
                  The postal address (complement) inherited from the User object (cardholder or parent depending on the `sendToParent` value). 
                  
                  This value cannot contain carriage return and is truncated at 50 characters. We advise you abide by the [mail carrier limitations](/guide/api-basics/data-format.html#addresses).
              deliveryAddress3:
                type: string
                maxLength: 35
                description: |
                  The postal address (complement2) inherited from the User object (cardholder or parent depending on the `sendToParent` value). 
                  
                  This value cannot contain carriage return and is truncated at 35 characters.
              deliveryPostcode:
                type: string
                maxLength: 10
                description: |
                  The postal code of the address inherited from the User object (cardholder or parent depending on the `sendToParent` value). 
              deliveryCity:
                type: string
                description: |
                  The city of the address inherited from the User object (cardholder or parent depending on the `sendToParent` value). 
                maxLength: 20
              deliveryCountry:
                type: string
                format: ISO 3166-1 alpha-2
                description: |
                  The country of the postal address inherited from the User object (cardholder or parent depending on the `sendToParent` value). 
                example: "FR"
              mobileSent:
                type: string
                description: Inherited from the cardholder's `phone`.
              limitsGroup:
                type: string
              permsGroup:
                type: string
                description: |
                  A code for a [preset of permissions](/guide/cards/restrictions-limits.html#options-permission-groups). It indicates whether the card main options (contactless, online payments, withdrawals, and international payments) are activated or not.
                enum:
                    - TRZ-CU-001
                    - TRZ-CU-002
                    - TRZ-CU-003
                    - TRZ-CU-004
                    - TRZ-CU-005
                    - TRZ-CU-006
                    - TRZ-CU-007
                    - TRZ-CU-008
                    - TRZ-CU-009
                    - TRZ-CU-010
                    - TRZ-CU-011
                    - TRZ-CU-012
                    - TRZ-CU-013
                    - TRZ-CU-014
                    - TRZ-CU-015
                    - TRZ-CU-016
              cardDesign:
                type: string
                description: | 
                  The `cardPrint` identifier, which defines the options and design of the card as part of your [Card Program](introduction.html#card-program).
              virtualConverted:
                type: integer
                description: |
                  Whether the card is a Virtual Card that has been converted into a Physical Card. Values can be:
                  * `1` – Physical card converted from a virtual card
                  * `0` – Not converted, virtual card only
                enum: [0, 1]
              physical:
                type: integer
                description: |
                  Whether the card is a physical card.
                enum: [0,1]
              optionAtm:
                type: integer
                description: |
                    Whether the card is usable on ATMs (withdrawal). See [Options & Permission groups](/guide/cards/restrictions-limits.html#options-permission-groups) for more information.
                enum: [0,1]
              optionForeign:
                type: integer
                description: |
                  Whether the card is usable abroad. See [Options & Permission groups](/guide/cards/restrictions-limits.html#options-permission-groups) for more information.
                enum: [0,1]
              optionOnline:
                type: integer
                description: |
                  Whether the card is usable online. See [Options & Permission groups](/guide/cards/restrictions-limits.html#options-permission-groups) for more information.
                enum: [0,1]
              optionNfc:
                type: integer
                description: |
                  Whether the card can be used for contactless payments. See [Options & Permission groups](/guide/cards/restrictions-limits.html#options-permission-groups) for more information.
                enum: [0,1]
              limitAtmYear:
                type: integer
                description: |
                  The ATM operations limit of the corresponding card for a sliding year.

                  See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                example: 0
              limitAtmMonth:
                type: integer
                description: |
                  ATM operations limit of the corresponding card for a sliding month.

                  See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                example: 0
              limitAtmWeek:
                type: integer
                description: |
                  ATM operations limit of the corresponding card for a sliding week.

                  See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                example: 2000
              limitAtmDay:
                type: integer
                description: |
                  ATM operations limit of the corresponding card for a single day.

                  See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                example: 1000
              limitAtmAll:
                type: integer
                description: | 
                  ATM operations limit of the corresponding card from beginning.

                  See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                example: 0
              limitPaymentYear:
                type: integer
                description: |
                  POS operations limit of the corresponding card for a sliding year.

                  See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                example: 0
              limitPaymentMonth:
                type: integer
                description: | 
                  POS operations limit of the corresponding card for a sliding month.

                  See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                example: 0
              limitPaymentWeek:
                type: integer
                description: | 
                  POS operations limit of the corresponding card for a sliding week.

                  See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                example: 3000
              limitPaymentDay:
                type: integer
                description: | 
                  POS operations limit of the corresponding card for a single day.

                  See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                example: 2000
              limitPaymentAll:
                type: integer
                description: | 
                  POS operations limit of the corresponding card for a single day.

                  See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
                example: 2000
              paymentDailyLimit:
                type: number
                format: float
                description: | 
                  POS operations limit for a single day including cents. The decimal delimiter must be ".". No default value.

                  For food vouchers use cases only.
              totalAtmYear:
                type: number
                format: float
                example: 5236.33
                description: The card yearly withdrawal amount.
              totalAtmMonth:
                type: number
                format: float
                example: 5236.33
                description: The card monthly withdrawal amount.
              totalAtmWeek:
                type: number
                format: float
                example: 5236.33
                description: The card weekly withdrawal amount.
              totalAtmDay:
                type: integer
                description: The card daily withdrawal amount.
              totalAtmAll:
                type: number
                format: float
                example: 5236.33
                description: The card total withdrawal amount.
              totalPaymentYear:
                type: number
                format: float
                example: 5236.33
                description: The card yearly spent amount.
              totalPaymentMonth:
                type: number
                format: float
                example: 5236.33
                description: The card monthly spent amount.
              totalPaymentWeek:
                type: number
                format: float
                example: 5236.33
                description: The card weekly spent amount.
              totalPaymentDay:
                type: number
                format: float
                example: 5236.33
                description: The card daily spent amount.
              totalPaymentAll:
                type: number
                format: float
                example: 5236.33
                description: The card total spent amount.
              createdBy:
                type: integer
                description: The clientId of the environment from which the card was created.
              createdDate:
                type: string
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                description: | 
                  Date `YYYY-MM-DD HH:mm:ss`
                example: "2025-01-10 15:49:53"
              modifiedBy:
                type: integer
                description: The clientId of the environment from which the card was modified.
              modifiedDate:
                type: string
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                description: | 
                  Date `YYYY-MM-DD HH:mm:ss`
                example: "2025-01-10 15:49:53"
              totalRows:
                type: integer
                nullable: true
                description: |
                  The total numbers of objects matching your search, for pagination purposes. Only valued in the first object of the returned page, `null` otherwise.
              designCode:
                type: string
                format: alphanumeric
                nullable: true
                maxLength: 2
                description: |
                  The customization code for the card design. If missing, falls back to the default Design Code. Learn more in the [Designs](/guide/cards/creation.html#designs-designcode) article.
              cardLanguages:
                type: string
                format: ISO 639-1 alpha-2
                maxLength: 8
                description: |
                  The language preferences for the card for [ATMs](/guide/overview/glossary.html#automated-teller-machine-atm), in the order of preference. For instance, for French and English, you have to enter "fren".

                  While this information is well taken into account in the card configuration, please note that the API will not return the value.
                    
                  Must be alphabetic and max. 8 characters. Format: [ISO 639-1 alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).
                example: "fren"
                nullable: true
              eventName:
                type: string
                description: Name of the Wallet, inherited from the wallet the card is attached to.
              eventAlias:
                type: string
                deprecated: true
              restrictionGroupLimits:
                minItems: 1
                type: array
                items:
                  type: object
                  properties:
                    paymentDailyLimit:
                      minimum: 0
                      exclusiveMinimum: true
                      type: number
                      format: float
                    mccRestrictionGroups:
                      minimum: 0
                      exclusiveMinimum: true
                      type: integer
                      format: int64
                    countryRestrictionGroups:
                      minimum: 0
                      exclusiveMinimum: true
                      type: integer
                      format: int64
                    merchantIdRestrictionGroups:
                      minimum: 0
                      exclusiveMinimum: true
                      type: integer
                      format: int64
              cancellationNumber:
                type: string
                description: | 
                  Number generated when the card `statusCode` is set to `STOLEN` or `LOST`.
              metadata:
                type: string
                nullable: true
              renewalDate:
                type: string
                description: |
                  Date on which the card was renewed (field populated for the original card only). Format: `YYYY-MM-DD`.
                example: "2025-08-22"
                nullable: true
              renewalType:
                type: string
                description: |
                  Indicates how the Card is to be renewed. `A` for automatic renewal, `N` for non-automatic renewal.
                enum: ["A", "N"]
                nullable: true
              originalCardId:
                type: integer
                description: The unique identifier of the original Card (field populated for renewed cards only).
                nullable: true
              logoId:
                type: string
                maxLength: 30
                description: |
                  The file name of the logo for the card, as uploaded to the manufacturer. Learn more in the [Logo](/guide/cards/creation.html#logo-logoid) article.
                example: "MyLogoFile.png"
              logoBackId:
                type: string
                maxLength: 30
                description: |
                  The file name of the logo for the back of the card, as uploaded to the manufacturer. Learn more in the [Back Logo](/guide/cards/creation.html#back-logo-logobackid) article.
                example: "MyBackLogoFile.png"
              packageId:
                type: string
                maxLength: 8
                description: Packaging reference for card shipping. Max. 8 characters.
                example: "Pkg123"
              customizedInfo:
                type: string
                description: Customized text to be displayed on the card.
              letterCustomizedInfo:
                type: string
                description: Customized text for the letter that is joined to the card.
              freeCustomizedInfo:
                type: string
                description: More customized text to be displayed on the card.
              deliveryMethod:
                type: integer
                description: | 
                  The method the manufacturer uses to send the cards (e.g., delivery with or without tracking). 
                  Learn more in the [Card Delivery Method](/guide/cards/creation.html#card-delivery-method-deliverymethod) article.
                nullable: true
              pinMailer:
                type: integer
                description: Whether the card manufacturer to send the card PIN code by letter.
                enum: [0,1]
                nullable: true
              batchDeliveryId:
                type: integer
                description: |
                  The [Batch delivery](/guide/cards/creation.html#batch-delivery-batchdeliveryid) identifier of the card.
                nullable: true
              sendToParent: 
                type: integer
                description: Whether the card should be sent to the cardholder's Parent User. 
                enum: [0,1]
              isTemporary:
                type: boolean
                default: false
                description: Whether the virtual card is a [temporary](/guide/cards/creation.html#creating-temporary-cards) one.
    MccList:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the list.
          example: "ec4896e4-21d3-45ab-8071-68a3b6c88002"
          nullable: true
          maxLength: 255
        description:
          type: string
          nullable: true
          description: The description of the list.
          example: "mcc_partners_whitelist"
        createdAt:
          type: string
          format: date-time
          description: The date and time at which the list was created.
          example: "2024-07-16T12:58:16+00:00"
        modifiedAt:
          type: string
          format: date-time
          description: The date and time at which the list was last updated.
          example: "2024-07-16T12:58:16+00:00"
        mccCount:
          type: number
          description: The number of MCCs included in the list.
      # Both properties are required
      required:
        - id

    MccLists:
      type: object
      properties:
        mccLists:
            type: array
            items:
              $ref: '#/components/schemas/MccList'
        nextPageToken:
            type: string
            nullable: true
            description: The pagination cursor to use as a query parameter to get to the next page of results.

    MerchantIdList:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the list.
          example: "7b447d57-414f-401f-a9a0-f2789a55f966"
          nullable: true
          maxLength: 255
        description:
          type: string
          description: The description of the list.
          example: "mid_partners_whitelist"
          nullable: true
        createdAt:
          type: string
          format: date-time
          description: The date and time at which the list was created.
          example: "2024-07-16T12:58:16+00:00"
        modifiedAt:
          type: string
          format: date-time
          description: The date and time at which the list was last updated.
          example: "2024-07-16T12:58:16+00:00"
        mccCount:
          type: integer
          description: The number of merchant Ids included in the list.

    MerchantIdLists:
      type: object
      properties:
        midLists:
          type: array
          items:
            $ref: '#/components/schemas/MerchantIdList'
        nextPageToken:
          type: string
          nullable: true
          description: The pagination cursor to use as a query parameter to get to the next page of results.

    MerchantIdGroupObject:
      type: object
      properties:
        merchantIdRestrictionGroups:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                description: The unique identifier of the Merchant ID restriction group.
              name:
                type: string
                description: The name of the Merchant ID restriction group.
              isWhitelist:
                type: boolean
                description: |
                  Indicates the kind of restriction: 
                  * `true` (default) – Allows only a specified list of merchant ids (whitelist)
                  * `false` – Allows all merchant ids except the specified list (blacklist)
                default: true
              merchants:
                type: array
                description: List of Merchant IDs (each item is a string).
                items:
                  type: string
              status:
                type: string
                description: The status of the Merchant ID restriction group.
                enum:
                  - CANCELED
                  - PENDING
                  - VALIDATED
              startDate:
                type: string
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                description: |
                  The date and time at which the restriction starts. 
                  
                  Format: `YYYY-MM-DD HH:mm:ss`
                example: "2025-01-10 15:49:53"
              createdDate:
                type: string
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                description: |
                  The date and time at which the restriction group was created. 
                  
                  Format: `YYYY-MM-DD HH:mm:ss`
                example: "2025-01-10 15:49:53"
    BulkUpdateObject:
      type: object
      properties:
        bulkUpdateId:
          type: string
          description: The unique identifier of the bulk updates object.
        bulkUpdateTag:
          description: The name of the bulk update request.
          type: string
          maxLength: 250
          nullable: true
          example: "new contract limits May 2025"
        bulkUpdateProgressStatus:
          type: string
          description: The status of the bulk update progress.
          enum: ["IN_PROGRESS","DONE","FAILED"]
        bulkUpdateType:
          type: string
          description: The type of bulk update.
          enum: ["CARD_LIMITS"]
        totalObjects:
          type: integer
          description: The total number of entities to be processed in the bulk.
          example: 25
        successfulUpdates:
          type: object
          nullable: true
          description: |
            Details regarding successful updates. Only available through the [GET /bulk-updates/{bulkUpdateId}](/guide/cards/restrictions-limits.html#update-limits-in-bulk) endpoint.
          properties:
            count:
              type: integer
              description: The number of successfully updated cards.
              example: 20
            cardIds:
              type: array
              items:
                type: integer
                description: The unique identifier of the card.
                example: 12345
        failedUpdates:
          type: object
          nullable: true
          description: |
            Details concerning failed updates. Only available through the [GET /bulk-updates/{bulkUpdateId}](/guide/cards/restrictions-limits.html#update-limits-in-bulk) endpoint.
          properties:
            count:
              type: integer
              description: Number of failed card updates.
              example: 5
            cards:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: integer
                    description: The unique identifier of the card.
                  reason:
                    type: string
                    description: The reason why the update failed for the given `id`.
                    enum: ["NOT_FOUND","INTERNAL_ERROR"]
        createdDate:
          type: string
          description: |
            The date and time at which the restriction group was created.

            Format: `YYYY-MM-DD HH:mm:ss`
          example: "2024-04-24 08:55:26"
        cardAttributes:
          type: object
          description: The updated attributes of the cards.
          properties:
            limitAtmYear:
              type: integer
              nullable: true
              description: |
                ATM operations limit of the card for a sliding year.

                See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
              example: 5000
            limitAtmMonth:
              type: integer
              nullable: true
              description: |
                ATM operations limit of the card for a sliding month.

                See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
              example: 2000
            limitAtmWeek:
              type: integer
              nullable: true
              description: |
                ATM operations limit of the card for a sliding week.

                See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
              example: 2000
            limitAtmDay:
              type: integer
              nullable: true
              description: |
                ATM operations limit of the card for a single day.

                See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
              example: 2000
            limitAtmAll:
              type: integer
              nullable: true
              description: |
                ATM operations limit of the card from the beginning.

                See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
            limitPaymentYear:
              type: integer
              nullable: true
              description: |
                POS operations limit of the card for a sliding year.

                See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
              example: 5000
            limitPaymentMonth:
              type: integer
              nullable: true
              description: |
                POS operations limit of the card for a sliding month.

                See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
            limitPaymentWeek:
              type: integer
              nullable: true
              description: |
                POS operations limit of the card for a sliding week.

                See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
              example: 2000
            limitPaymentDay:
              type: integer
              nullable: true
              description: |
                POS operations limit of the card for a sliding day.

                See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
              example: 2000
            limitPaymentAll:
              type: integer
              nullable: true
              description: |
                POS operations limit of the card from the beginning.

                See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
            paymentDailyLimit:
              type: number
              format: float
              nullable: true
              description: |
                POS operations limit of the card for a single day, including cents.

                For food vouchers use cases only.
              example: 25.55
            restrictionGroupLimits:
              type: array
              items:
                type: object
                properties:
                  paymentDailyLimit:
                    type: number
                    format: float
                    minimum: 0
                    exclusiveMinimum: true
                  mccRestrictionGroups:
                    type: integer
                    format: int64
                    minimum: 0
                    exclusiveMinimum: true
                    nullable: true
                  countryRestrictionGroups:
                    type: integer
                    format: int64
                    minimum: 0
                    exclusiveMinimum: true
                    nullable: true
                  merchantIdRestrictionGroups:
                    type: integer
                    format: int64
                    minimum: 0
                    exclusiveMinimum: true
                    nullable: true
    ScaWalletObject:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the SCA Wallet.
          example: "310a488efab74ba2bc699b4f841b0bc4"
        status:
          type: string
          description: The status of the SCA Wallet.
          enum:
            - ACTIVE
            - CREATED
            - CREATING
            - DELETED
            - INITIALIZING
          nullable: true
        subStatus:
          type: string
          enum:
            - CREATING_IN_PROGRESS
            - CREATED_BLOCKED
            - CREATED_READY
            - INITIALIZING_MOBILE
            - ACTIVATED_LOGGED_IN
            - ACTIVATED_LOGGED_OUT
            - DELETED_BY_ISSUER
            - DELETED_UNINSTALLED
          nullable: true
        passcodeStatus:
          type: string
          enum:
            - NONE
            - NOT_SET
            - SET
            - TO_BE_CHANGED
          nullable: true
        locked:
          type: boolean
          nullable: true
        lockReasons:
          type: array
          items:
            type: string
            enum:
              - FRAUDULENT_USE_SUSPECTED_BY_CLIENT
              - FRAUDULENT_USE_SUSPECTED_BY_ISSUER
              - ISSUER
              - LOST_DEVICE
              - STOLEN_DEVICE
              - TERMINATE_SERVICE
          nullable: true
        lockMessage:
          type: string
          nullable: true
          example: "Deleted"
        settingsProfile:
          type: string
          nullable: true
          enum:
            - default
            - webauthn
        mobileWallet:
          type: object
          properties:
            appBuildNumber:
              type: string
              example: "v04-04-06-06-02-02"
            sdkVersion:
              type: string
              example: "2.4.11"
            os:
              type: string
              example: "ANDROID"
            osVersion:
              type: string
              example: "13"
            brand:
              type: string
              example: "samsung"
            productModel:
              type: string
              example: "SM-A226B"
            deviceId:
              type: string
              example: "0097e609be9335cc"
            deviceIdType:
              type: string
              example: "ANDROID_ID"
            productFingerprint:
              type: string
              example: "samsung/a45xnseea/a22x:13/TP1A.220924.014/A2200XXU5DWC1:user/release-keys"
            secretFingerprint:
              type: string
              example: "0x1754726a90d3664350f8118047b1482d7c17d521f466da772a09b5be2cc67eaa"
            root:
              type: string
              example: "0"
            pushMessagingId:
              type: string
              example: "fTUGDWeXQnW4fgTBvpKvWo:APA91bEevu80iZJm3_59UYDQAiBiJYoASQ2TZfGgCwmCziPqe_ipnh3ZEFV5tGzPN3JpXjO4xRFA-Kmy3JEjgPO1mPPk6WxjEWcyDIiM33DkTOsvGxekG7f5d1xh4YAz6BQLLHkp0usC"
            pushMessagingProvider:
              type: string
              example: "FIREBASE"
            mobileUpdateDate:
              type: string
              format: date-time
              example: "2024-05-03T09:43:15Z"
            lastEligibilityCheck:
              type: string
              format: date-time
              example: "2024-05-03T09:43:15Z"
            nfc:
              type: boolean
            emulator:
              type: boolean
            appleTeamId:
              type: string
              example: "567890"
        activationCode:
          type: string
          description: The code to authenticate the end user (mobile provisioning).
        creationDate:
          type: string
          format: date-time
          description: The date and time at which the SCA Wallet was created.
          nullable: true
          example: "2024-05-30T16:09:22+02:00"
        deletionDate:
          type: string
          format: date-time
          description: The date and time at which the SCA Wallet was deleted.
          nullable: true
          example: "2024-05-30T16:09:22+02:00"
        activationCodeExpiryDate:
          type: string
          format: date-time
          description: |
            The date and time before which the `activationCode` must be use for mobile provisioning.
          nullable: true
          example: "2024-05-30T16:29:22+02:00"
        authenticationMethods:
          type: array
          oneOf:
            - $ref: '#/components/schemas/EntrustAuthenticationMethods'
            - $ref: '#/components/schemas/WebAuthnAuthenticationMethods'
          items:
            type: object
          nullable: true
        invalidActivationAttempts:
          type: string
          nullable: true
        userId:
          type: string
          nullable: true
          description: The unique identifier of the user who owns the SCA Wallet.
          example: "4567890"
        scaWalletTag:
          type: string
          nullable: true
          maxLength: 256
          description: |
            Custom value for the SCA Wallet. Can be used to name the device for which the new SCA Wallet is created. 
        clientId:
          type: string
          description: The identifier of the environment the SCA Wallet belongs to.
          example: "12345"
        activationDate:
          type: string
          format: date-time
          nullable: true
          description: The date and time at which the SCA Wallet was activated.
          example: "2025-03-21T11:46:00+01:00"
        lockDate:
          type: string
          format: date-time
          description: | 
            The date and time at which the SCA Wallet was locked.
          nullable: true
          example: "2025-03-21T11:46:00+01:00"
        unlockDate:
          type: string
          format: date-time
          description: | 
            The date and time at which the SCA Wallet was unlocked.
          nullable: true
          example: "2025-03-21T11:46:00+01:00"
        resetPinDate:
          type: string
          format: date-time
          description: | 
            The date and time at which the SCA Wallet PIN was reset.
          nullable: true
          example: "2025-03-21T11:46:00+01:00"
    
    EntrustAuthenticationMethods:
      properties:
        type:
          description: The type of the authentication method.
          type: string
          nullable: false
          enum:
            - NONE
            - CLOUD_PIN
            - HYBRID_PIN
            - DEVICE_BIOMETRIC
            - SCREEN_UNLOCK
            - CONSENT
        usages:
          description: The list of actions for which the authentication method can be used.
          type: array
          nullable: false
          items:
            type: string
            enum:
              - DIGITAL_CARD
              - PAYMENT
              - WALLET_MANAGEMENT
              - STRONG_CUSTOMER_AUTHENTICATION
        parameters:
          type: object
          description: Parameters specific to a given authentication method, depending on its type and the actions it can be used for.
          properties:
            strength:
              description: |
                Authentication method strength: information to order several authentication methods. Required for `PAYMENT` actions.
              type: integer
            maxAttempts:
              description: |
                Maximum number of attempts before being locked with an invalid authentication method. Required for `CLOUD_PIN` and `HYBRID_PIN` types.
              type: integer
              minimum: 1
              maximum: 100
            maxPaymentAmount:
              description: Maximum payment amount using this authentication method, in the currency of the wallet.
              type: integer
              example: 1000
            maxPaymentsAmount:
              description: Maximum cumulated payments amount using this authentication method, in the currency of the wallet.
              type: integer
              example: 10000
            maxPaymentsNumber:
              description: Maximum number payments amount using this authentication method.
              type: integer
              example: 150
            otherCurrencies:
              description: Whether currencies different from the one of the wallet are supported and how they are supported.
              type: string
              enum:
                - NO
                - LVP
                - ALL
              nullable: false
            lowerCvmAmountMax:
              description: Maximum amount of a transaction done with a CVM of lower strength.
              type: number
              example: 50
            validityDuration:
              description: During a payment, duration (in seconds) of the validity of customer authentication (e.g., PIN code, fingerprint).
              type: integer
              nullable: false

    WebAuthnAuthenticationMethods:
      properties:
        userHandle:
          type: string
          example : "dGVzdEB3ZWJhdXRobg"
        publicKeyCredentialId:
          type: string
          example: "-7TzaTMjA3dk-1fLf3fEch_Rwxr3hxB0-yaxQXpyEeo"
        aaguid:
          type: string
          example: "adce0002-35bc-c60a-648b-0b25f1f09975"
        uvInitialized:
          type: boolean
        attestationType:
          type: string
          example: "self"
        backupEligible:
          type: boolean
        counter:
          type: integer
        otherUI:
          type: string
          nullable: true
        type:
          type: string
          example: "public-key"
        transports:
          type: array
          items:
            type: string
            enum: 
              - ble
              - hybrid
              - internal
              - nfc
              - usb
        backupStatus:
          type: boolean
        credentialPublicKey:
          type: string
          example: "pQECAyYgASFYIIXaEy2MmEtWgf89vaByEQU-sQ1qY9spLJBhrIfp4o6rIlggZ8YQEc4Zq2g51o0hYKqqWcprI5yqvTz5P7-frvEHIzI"
        trustPath:
          type: object
          properties:
            type:
              type: string
              example: "Webauthn\\TrustPath\\EmptyTrustPath"

    TaxResidenceObject:
      type: object
      properties:
        taxResidences:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                description: The unique identifier of the Tax Residence.
              userId:
                type: integer
                description: The unique identifier of the User.
              country:
                type: string
                description: The country code for the country of Tax Residence.
                example: "FR"
              taxPayerId:
                type: string
                description: | 
                  The Tax Identification Number (TIN) or Tax Code of the User.
              liabilityWaiver:
                type: boolean
                description: The waiver exempting Treezor from liability in case of a missing TIN.
              createdDate:
                type: string
                description: The date of creation of the Tax Residence object.
                example: "2025-01-10 15:49:53"
              lastUpdate:
                type: string
                description: The date and time at which the Tax Residence has been updated.
                example: "2025-01-10 15:49:53"
              deletedDate:
                type: string
                description: The date and time at which the Tax Residence has been deleted.
                example: "2025-01-10 15:49:53"
              isDeleted:
                type: boolean
                description: Whether or not the Tax Residence object was deleted.
    TransferObject:
      type: object
      properties:
        transfers:
          type: array
          items:
            type: object
            properties:
              transferId:
                type: integer
                description: The unique identifier of the Transfer.
              transferStatus:
                type: string
                description: |
                  The status of the Transfer. See [Transfer statuses](/guide/transfers/introduction.html#transfer-statuses-codestatus) for more information.
                enum:
                  - CANCELED
                  - PENDING
                  - VALIDATED
              transferTag:
                type: string
                maxLength: 250
                description: |
                  Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
                  
                  Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
              walletId:
                type: integer
                description: The unique identifier of the debited Wallet.
              walletTypeId:
                type: integer
                description: |
                  The type of the debited Wallet:

                  * `9` – Electronic Money Wallet 
                  * `10` – Payment Account Wallet
                enum: [9,10,15]
              beneficiaryWalletId:
                type: integer
                description: The unique identifier of the credited Wallet.
              beneficiaryWalletTypeId:
                type: integer
                description: |
                  The type of Wallet. Learn more in the [Wallet Types](/guide/wallets/introduction.html#types-of-wallets) documentation.
                enum: [9,10,15]
              # transferDate:
              #   type: string
              #   deprecated: true
              #   description: | 
              #     The date of the Transfer. Format: YYYY-MM-DD
              walletEventName:
                type: string
                description: The name of the debited Wallet.
                example: "Main Wallet"
              walletAlias:
                type: string
                deprecated: true
              beneficiaryWalletEventName:
                type: string
                description: The name of the credited Wallet.
              beneficiaryWalletAlias:
                type: string
                deprecated: true
              amount:
                type: string
                description: The amount of the transfer.
                example: "10.34"
              currency:
                type: string
                description: The currency of the transfer.
              label:
                type: string
                description: | 
                  The label of the transfer, to display on the receiver's statement for instance.
                maxLength: 140
              transferTypeId:
                type: integer
                description: |
                  The type of transfer:
                  * `1` – Wallet to wallet 
                  * `2` – Card transaction
                  * `3` – Client fees
                  * `4` – Credit note
                enum: [1,2,3,4]
              createdDate:
                type: string
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                description: |
                  The date and time at which the transfer is created. 
                  
                  Format: `YYYY-MM-DD HH:mm:ss`
                example: "2024-03-23 12:34:23"
              modifiedDate:
                type: string
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                description: | 
                  The date and time at which the transfer is updated. 
                  
                  Format: `YYYY-MM-DD HH:mm:ss`
                example: "2024-03-23 12:34:23"
              totalRows:
                type: integer
                description: |
                  The total numbers of objects matching your search, for pagination purposes. Only valued in the first object of the returned page, `null` otherwise.
              foreignId:
                type: string
                deprecated: true
              partnerFee:
                type: string
                deprecated: true
              codeStatus:
                type: string
                description: |
                  The code for the status of the transfer. See [Transfer statuses](/guide/transfers/introduction.html#transfer-statuses-codestatus) for more information.
                enum: ["150001", "150002", "150003", "150004", "150005", "150006"]
              informationStatus:
                type: string
                description: Additional information regarding the status of the transfer (if any).
              metadata:
                type: string
                deprecated: true
    UserObject:
      type: object
      properties:
        users:
          type: array
          items:
            type: object
            properties:
              userId:
                type: integer
                description: The unique identifier of the User.
                example: 12345
              userStatus:
                type: string
                description: The status of the User.
                enum:
                  - CANCELED
                  - PENDING
                  - VALIDATED
              userTypeId:
                type: integer
                description: The type of the user.
                enum: [1, 2, 3, 4]
              userTag:
                type: string
                maxLength: 250
                description: |
                  Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
                  
                  Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
              parentUserId:
                type: integer
                description: The unique identifier of the parent user (if any).
              parentType:
                type: string
                description: |
                  The type of relationship between the parent and the current users.

                  You may read more about [parent-children relationships](/guide/users/parent-children.html).
                enum:
                  - ''
                  - employee
                  - leader
                  - shareholder
              controllingPersonType:
                type: integer
                description: |
                  Type of relationship:
                  * `0` – None (default)
                  * `1` – Shareholder
                  * `2` – Other_relationship
                  * `3` – Director

                  You may read more about [parent-children relationships](/guide/users/parent-children.html).
                enum: [0, 1, 2, 3]
                default: 0
              employeeType:
                type: integer
                description: | 
                  The role of the user in [parent-children relationships](/guide/users/parent-children.html):
                  * `0` – None (default)
                  * `1` – Leader
                  * `2` – Employee
                enum: [0, 1, 2]
                default: 0
              specifiedUSPerson:
                type: integer
                description: |
                  When set to `1`, the user must have a US tax residence declared.
            
                  Should be set to `0` otherwise.
            
                  You may read more about who is considered a US Person in the [dedicated article](/guide/users/tax-residence.html).
                enum: [0, 1]
              title:
                type: string
                description: |
                  The title of the user, which can be one of the following:
                  * `M` – Stands for mister (Mr.)
                  * `MME` – Stands for missus (Mrs.)
                  * `MLLE` – Stands for miss
                  * `MX` – Gender-neutral title
                example: MX
                enum:
                  - ''
                  - 'M'
                  - 'MLLE'
                  - 'MME'
                  - 'MX'
              firstname:
                type: string
                description: The first name of the User.
                example: Alex
              lastname:
                type: string
                description: The last name of the User.
                example: Oak
              middleNames:
                type: string
                description: The middle names of the User, if any.
              birthday:
                type: string
                format: date
                description: |
                  The birth date of the Physical User (`userTypeId` `1`). The user can't be more than a 100 years old upon reation.
                example: "1990-10-29"
              email:
                type: string
                maxLength: 200
                description: |
                  The email of the User. Must be valid and unique.

                  Please note only active users are checked for email uniqueness. `CANCELED` user emails can be reused to facilitate account re-creation.
                example: "aoak@example.com"
              address1:
                type: string
                minLength: 3
                maxLength: 150
                oneOf:
                  - title: France (FR)
                    type: string
                    minLength: 3
                    maxLength: 150
                    # pattern: "^[a-zA-Z0-9À-ÖØ-öø-ÿœÆŒ\\s.,\\[\\]{}€@#\\-:( )/=' +?!\"%*;°_]+$"
                    description: |
                      The User postal address (main) for users whose `distributionCountry` is `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                      
                      **Characters:** Supports uppercase/lowercase letters with accents, digits, spaces, and the following symbols: `., [] {} € @ # - : ( ) / = ' + ? ! " % & * ; ° _`.
                    example: "14 Rue de la Paix"
                  - title: Other countries
                    type: string
                    minLength: 3
                    maxLength: 150
                    # pattern: "^[\\u0020-\\u007E\\u00A0-\\u00FF\\u0152\\u0153\\u0160\\u0161\\u0178\\u017D\\u017E\\u20AC]+$"
                    description: |
                      The User postal address (main) for users whose `distributionCountry` is other than `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                      
                      **Characters:** Full ISO 8859-15 standard character set.
                    example: "123 Main Street"
              address2:
                type: string
                minLength: 3
                maxLength: 150
                oneOf:
                    - title: France (FR)
                      type: string
                      minLength: 3
                      maxLength: 150
                      # pattern: "^[a-zA-Z0-9À-ÖØ-öø-ÿœÆŒ\\s.,\\[\\]{}€@#\\-:( )/=' +?!\"%*;°_]+$"
                      description: |
                        The User postal address (complement) for users whose `distributionCountry` is `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                        
                        **Characters:** Supports uppercase/lowercase letters with accents, digits, spaces, and the following symbols: `., [] {} € @ # - : ( ) / = ' + ? ! " % & * ; ° _`.
                    - title: Other countries
                      type: string
                      minLength: 3
                      maxLength: 150
                      # pattern: "^[\\u0020-\\u007E\\u00A0-\\u00FF\\u0152\\u0153\\u0160\\u0161\\u0178\\u017D\\u017E\\u20AC]+$"
                      description: |
                        The User postal address (complement) for users whose `distributionCountry` is other than `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                        
                        **Characters:** Full ISO 8859-15 standard character set.
              address3:
                type: string
                minLength: 3
                maxLength: 150
                oneOf:
                  - title: France (FR)
                    type: string
                    minLength: 3
                    maxLength: 150
                    # pattern: "^[a-zA-Z0-9À-ÖØ-öø-ÿœÆŒ\\s.,\\[\\]{}€@#\\-:( )/=' +?!\"%*;°_]+$"
                    description: |
                      The User postal address (complement2) for users whose `distributionCountry` is `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                      
                      **Characters:** Supports uppercase/lowercase letters with accents, digits, spaces, and the following symbols: `., [] {} € @ # - : ( ) / = ' + ? ! " % & * ; ° _`.
                  - title: Other countries
                    type: string
                    minLength: 3
                    maxLength: 150
                    # pattern: "^[\\u0020-\\u007E\\u00A0-\\u00FF\\u0152\\u0153\\u0160\\u0161\\u0178\\u017D\\u017E\\u20AC]+$"
                    description: |
                      The User postal address (complement2) for users whose `distributionCountry` is other than `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                      
                      **Characters:** Full ISO 8859-15 standard character set.
              postcode:
                oneOf:
                  - title: European 5-Digit Format
                    type: string
                    # pattern: '^\d{5}$'
                    minLength: 5
                    maxLength: 5
                    description: The postal code of the address. Applicable for BE, DE, ES, FR, IT. Must always correspond with the provided city.
                    example: "75001"
                  - title: International Format
                    type: string
                    maxLength: 20
                    format: ISO 8859-15 subset
                    # pattern: "^[a-zA-Z0-9'\\-,. áàâäãåçéèêëíìîïñóòôöõúùûüýÿæœÁÀÂÄÃÅÇÉÈÊËÍÌÎÏÑÓÒÔÖÕÚÙÛÜÝŸÆŒ€]+$"
                    description: The postal code of the address. Applicable for all other countries. Must always correspond with the provided city.
                    example: "SW1A 1AA"
              city:
                type: string
                description: The User address city.
              state:
                type: string
                maxLength: 100
                # pattern: "^[a-zA-ZÀ-ÖØ-öø-ÿœÆŒŠšŽžŸ\\s'-]+$"
                description: |
                  The state of the user address.
                  
                  **Validation Rules:**
                  - **Characters:** Supports the ISO 8859-15 set, including standard letters, accented characters, spaces, hyphens, and apostrophes.
                  - **Anti-Spam:** A character cannot be repeated more than 3 times consecutively (e.g., "AAAA" is invalid).
              country:
                type: string
                format: ISO 3166-1 alpha-2
                description: The User address country.
                example: "FR"
              countryName:
                type: string
                description: The name of the country.
                example: "France"
              distributionCountry:
                type: string
                nullable: true
                description: | 
                  The country in which the end user is using your services.
                format: ISO 3166-1 alpha-2
                example: "FR"
                enum:
                  - BE
                  - DE
                  - ES
                  - FR
                  - IT
                  - NL
              secondaryAddress1:
                type: string
                minLength: 3
                maxLength: 150
                oneOf:
                  - title: France (FR)
                    type: string
                    minLength: 3
                    maxLength: 150
                    # pattern: "^[a-zA-Z0-9À-ÖØ-öø-ÿœÆŒ\\s.,\\[\\]{}€@#\\-:( )/=' +?!\"%*;°_]+$"
                    description: |
                      The User secondary postal address (main) for users whose `distributionCountry` is `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                      
                      **Characters:** Supports uppercase/lowercase letters with accents, digits, spaces, and the following symbols: `., [] {} € @ # - : ( ) / = ' + ? ! " % & * ; ° _`.
                    example: "14 Rue de la Paix"
                  - title: Other countries
                    type: string
                    minLength: 3
                    maxLength: 150
                    # pattern: "^[\\u0020-\\u007E\\u00A0-\\u00FF\\u0152\\u0153\\u0160\\u0161\\u0178\\u017D\\u017E\\u20AC]+$"
                    description: |
                      The User secondary postal address (main) for users whose `distributionCountry` is other than `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                      
                      **Characters:** Full ISO 8859-15 standard character set.
                    example: "123 Main Street"
              secondaryAddress2:
                type: string
                minLength: 3
                maxLength: 150
                oneOf:
                  - title: France (FR)
                    type: string
                    minLength: 3
                    maxLength: 150
                    # pattern: "^[a-zA-Z0-9À-ÖØ-öø-ÿœÆŒ\\s.,\\[\\]{}€@#\\-:( )/=' +?!\"%*;°_]+$"
                    description: |
                      The User secondary postal address (complement) for users whose `distributionCountry` is `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                      
                      **Characters:** Supports uppercase/lowercase letters with accents, digits, spaces, and the following symbols: `., [] {} € @ # - : ( ) / = ' + ? ! " % & * ; ° _`.
                  - title: Other countries
                    type: string
                    minLength: 3
                    maxLength: 150
                    # pattern: "^[\\u0020-\\u007E\\u00A0-\\u00FF\\u0152\\u0153\\u0160\\u0161\\u0178\\u017D\\u017E\\u20AC]+$"
                    description: |
                      The User secondary postal address (complement) for users whose `distributionCountry` is other than `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                      
                      **Characters:** Full ISO 8859-15 standard character set.
              secondaryAddress3:
                type: string
                minLength: 3
                maxLength: 150
                oneOf:
                  - title: France (FR)
                    type: string
                    minLength: 3
                    maxLength: 150
                    # pattern: "^[a-zA-Z0-9À-ÖØ-öø-ÿœÆŒ\\s.,\\[\\]{}€@#\\-:( )/=' +?!\"%*;°_]+$"
                    description: |
                      The User secondary postal address (complement2) for users whose `distributionCountry` is `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                      
                      **Characters:** Supports uppercase/lowercase letters with accents, digits, spaces, and the following symbols: `., [] {} € @ # - : ( ) / = ' + ? ! " % & * ; ° _`.
                  - title: Other countries
                    type: string
                    minLength: 3
                    maxLength: 150
                    # pattern: "^[\\u0020-\\u007E\\u00A0-\\u00FF\\u0152\\u0153\\u0160\\u0161\\u0178\\u017D\\u017E\\u20AC]+$"
                    description: |
                      The User secondary postal address (complement2) for users whose `distributionCountry` is other than `FR`. Cannot contain carriage return and cannot have the same character more than 3 times in a row.
                      
                      **Characters:** Full ISO 8859-15 standard character set.
              secondaryPostcode:
                oneOf:
                  - title: European 5-Digit Format
                    type: string
                    # pattern: '^\d{5}$'
                    minLength: 5
                    maxLength: 5
                    description: The postal code of the address. Applicable for BE, DE, ES, FR, IT. Must always correspond with the provided city.
                    example: "75001"
                  - title: International Format
                    type: string
                    maxLength: 20
                    format: ISO 8859-15 subset
                    # pattern: "^[a-zA-Z0-9'\\-,. áàâäãåçéèêëíìîïñóòôöõúùûüýÿæœÁÀÂÄÃÅÇÉÈÊËÍÌÎÏÑÓÒÔÖÕÚÙÛÜÝŸÆŒ€]+$"
                    description: The postal code of the address. Applicable for all other countries. Must always correspond with the provided city.
                    example: "SW1A 1AA"
              secondaryCity:
                type: string
              secondaryState:
                type: string
                maxLength: 100
                # pattern: "^[a-zA-ZÀ-ÖØ-öø-ÿœÆŒŠšŽžŸ\\s'-]+$"
                description: |
                  The state of the user secondary address.
                  
                  **Validation Rules:**
                  - **Characters:** Supports the ISO 8859-15 set, including standard letters, accented characters, spaces, hyphens, and apostrophes.
                  - **Anti-Spam:** A character cannot be repeated more than 3 times consecutively (e.g., "AAAA" is invalid).
              secondaryCountry:
                type: string
                description: Format ISO 3166-1 alpha-2
                format: ISO 3166-1 alpha-2
                example: "FR"
              clientId:
                type: string
                description: The unique identifier of the Treezor environment.
                example: "12345"
              phone:
                type: string
                description: |
                  The phone number of the user in international **E.164 format**. 
                  It must start with a plus sign (`+`) followed by the country code and the national number.
                # pattern: '^\+[1-9]\d{1,14}$'
                example: "+33123456789"
              mobile:
                type: string
                description: |
                  The mobile phone number of the user in international **E.164 format**. 
                  It must start with a plus sign (`+`) followed by the country code and the national number.
                # pattern: '^\+[1-9]\d{1,14}$'
                example: "+33123456789"
              nationality:
                type: string
                description: Format ISO 3166-1 alpha-2
                format: ISO 3166-1 alpha-2
                example: "FR"
              nationalityOther:
                type: string
                description: Format ISO 3166-1 alpha-2
                format: ISO 3166-1 alpha-2
                example: "FR"
              placeOfBirth:
                type: string
                maxLength: 100
                # pattern: "^[a-zA-Z0-9À-ÖØ-öø-ÿœÆŒ\\s'-]+$"
                description: |
                  The city in which the Physical User was born.
                  
                  **Validation Rules:**
                  - **Geographic Accuracy:** Must be an existing city located within the provided `birthCountry`.
                  - **Characters:** Alphanumeric characters, spaces, hyphens, and apostrophes are allowed.
                  - **Forbidden:** Special symbols (e.g., `/`, `@`, `#`, `!`) and commas are prohibited.
                  - **ISO 8859-15:** Supports standard European accented characters and ligatures.
                example: "Aix-en-Provence"
              birthCountry:
                type: string
                description: The country in which the User was born.
                format: ISO 3166-1 alpha-2
                example: "FR"
              occupation:
                type: string
                description: Free field to specify the occupation of the user. 
              incomeRange:
                type: string
                deprecated: true
              legalName:
                oneOf:
                  - title: French SIREN Format
                    type: string
                    minLength: 1
                    maxLength: 100
                    # pattern: "^[a-zA-Z0-9ÀÂÄÇÉÈÊËÎÏÔÖÙÛÜŸàâäçéèêëîïôöùûüÿæœÆŒ .,\\[\\]{}€@#\\-:( )/=' +?!\"%&*;<>=°_]+$"
                    description: |
                      The official name of the legal entity (or self-employed user) as registered with national authorities. Compliant with the French SIREN naming standards; must follow the SIREN referential (supports specific accents, ligatures like 'œ', and symbols).

                      If you're issuing cards, please not this value automatically populates the `embossedLegalName` field which has a max. length of 20 characters.
                  - title: European Standard Format
                    type: string
                    format: ISO 8859-15
                    minLength: 1
                    maxLength: 100
                    # pattern: "^[\\u0020-\\u007E\\u00A0-\\u00FF\\u0152\\u0153\\u0160\\u0161\\u0178\\u017D\\u017E\\u20AC]+$"
                    description: | 
                      The official name of the legal entity (or self-employed user) as registered with national authorities. Standard ISO 8859-15 characters for ES, IT, DE, BE, NL.

                      If you're issuing cards, please not this value automatically populates the `embossedLegalName` field which has a max. length of 20 characters.
              legalNameEmbossed:
                type: string
                description: |
                  Populated from the `legalName` value.
                maxLength: 20
              legalRegistrationNumber:
                oneOf:
                  - title: France (SIREN/SIRET)
                    type: string
                    # pattern: '^\d{9,14}$'
                    description: |
                      The official registration number of the legal entity. 
                      Mandatory for FR. Numeric characters only (9 or 14 digits).
                      If provided, the `country` field must be present as well.
                    example: "12345678901234"
                  - title: Spain (NIF)
                    type: string
                    # pattern: '^[A-Z]\d{7}[A-Z0-9]$'
                    description: |
                      The official registration number of the legal entity. 
                      Mandatory for ES. Structure: 1 letter + 7 digits + 1 control character (letter or digit).
                      If provided, the `country` field must be present as well.
                    example: "A1234567B"
                  - title: Italy (Numero REA)
                    type: string
                    # pattern: '^[A-Z]{2}\d+$'
                    description: |
                      The official registration number of the legal entity.
                      Mandatory for IT. Structure: 2-letter Provincial Code + digits.
                      If provided, the `country` field must be present as well.
                    example: "RM123456"
                  - title: Germany & Global (Alphanumeric)
                    type: string
                    # pattern: '^[a-zA-Z0-9]+$'
                    description: |
                      The official registration number of the legal entity. 
                      Optional for DE. Alphanumeric for all other countries.
                      If provided, the `country` field must be present as well.
                    example: "HRB12345"
              legalTvaNumber:
                type: string
                minLength: 3
                maxLength: 20
                description: |
                  The VAT number of the legal entity.
                  
                  This field is referred to as **Codice fiscale** in Italy and **Umsatzsteuer-ID** in Germany.
                  
                  **KYB Requirements:**
                  - **Mandatory:** For Italy (IT) and Spain (ES).
                  - **Optional:** For France (FR) and Germany (DE).
                # pattern: '^[a-zA-Z0-9]{3,20}$'
                example: "IT12345678901"
              legalRegistrationDate:
                type: string
                format: date
                description: | 
                  The date on which the legal entity was officially registered with the relevant national authorities. Must be in the past.
                example: "2020-01-21"
              legalForm:
                type: string
                description: |
                  The legal form/category of the company. See the [Legal Forms](/guide/users/introduction.html#legal-forms-legalform) section for more information.
              legalShareCapital:
                type: integer
              entityType:
                type: integer
                deprecated: true
                enum: [1, 2, 3, 4, 5]
              legalSector:
                type: string
                description: |
                  The business sector of the legal entity. Either a 4-digit code if NACE or a 5-digit code followed by an uppercase letter if NAF, depending on the value of the `legalSectorType`.
              legalAnnualTurnOver:
                type: string
                description: The Business annual turnover (in k€).
                enum:
                  - ''
                  - '0-39'
                  - '40-99'
                  - '100-249'
                  - '250-999'
                  - '1000-2999'
                  - '3000-9999'
                  - '10000-99999'
                  - '100000-*'
              legalNetIncomeRange:
                type: string
                description: The Business net income range (in k€). Negative values are only accepted for legal entities.
                enum:
                  - ''
                  - '*--500'
                  - '-499--150'
                  - '-149--50'
                  - '-49--10'
                  - '-9--1'
                  - '0-4'
                  - '5-9'
                  - '10-49'
                  - '50-149'
                  - '150-499'
                  - '500-*'
              legalNumberOfEmployeeRange:
                type: string
                description: The number of employees of the legal entity.
                enum:
                  - ''
                  - '1-9'
                  - '10-99'
                  - '100-249'
                  - '250-*'
              effectiveBeneficiary:
                type: integer
                description: |
                  The effective beneficiary shares of the legal entity (e.g., for a beneficiary holding 70% of a company, value must be `70`). For shareholders only.
              kycLevel:
                type: integer
                description: |
                  * `0` – NONE
                  * `1` – LIGHT
                  * `2` – REGULAR
                  * `3` – STRONG
                  * `4` – REFUSED
                  * `5` – PREVALIDATED
                  * `6` – ENHANCED
                enum: [0, 1, 2, 3, 4, 5, 6]
              kycReview:
                type: integer
                description: |
                  * `0` – NONE
                  * `1` – PENDING
                  * `2` – VALIDATED
                  * `3` – REFUSED
                  * `4` – INVESTIGATING (deprecated)
                  * `5` – CLOSED (deprecated)
                  * `6` – REVIEW_OPEN
                  * `7` – REVIEW_PENDING
                enum: [0, 1, 2, 3, 6, 7]
              kycReviewComment:
                type: string
                description: |
                  A comment set by Treezor upon [KYC review](/guide/user-verification/introduction.html). It concatenates information for each KYC Review update, with the date, the `kycReview` and `kycLevel` values, and the comment from Treezor.
              isFreezed:
                type: integer
                deprecated: true
                description: deprecated
              isFrozen:
                type: integer
                description: |
                  Indicates that the user is under restriction and some operations are blocked. See [Restricted users](/guide/users/restricted-users.html#types-of-user-restrictions) for more information.
                enum: [0, 1]
              language:
                type: string
                description: |
                  The preferred language of the User, in the ISO 639 alpha-2 format.
                format: ISO 639-1
                example: "FR"
              optInMailing:
                type: integer
              sepaCreditorIdentifier:
                type: string
                description: |
                  The 13-character long [SEPA Creditor Identifier](/guide/overview/glossary.html#sepa-creditor-identifier-sci) of the User.
                readOnly: true
              taxNumber:
                type: string
                deprecated: true
              taxResidence:
                type: string
                deprecated: true
              position:
                type: string
              personalAssets:
                type: string
                deprecated: True
              activityOutsideEu:
                type: integer
                description: Whether the entity and its business units, subsidiaries, and joint ventures have a commercial activity outside of the European Union.
                enum: [0, 1]
              economicSanctions:
                type: integer
                description: Whether the entity, its subsidiaries, entities, employees, directors, beneficial owners, or joint ventures are subject to Economic Sanctions.
                enum: [0, 1]
              residentCountriesSanctions:
                type: integer
                description: Whether the entity, its subsidiaries, or joint ventures, located within or operating from any countries or territories are subject to Comprehensive Sanctions.
                enum: [0, 1]
              involvedSanctions:
                type: integer
                description: |
                  Whether the entity, its subsidiaries, or joint ventures, are engaged in transactions, investments, business, or other dealings that directly or indirectly involve or benefit:
                  * Any countries or territories subject to Comprehensive Sanctions, or
                  * Any person or entity which is the target of any Sanctions (“Sanctioned Targets”).
                enum: [0, 1]
              entitySanctionsQuestionnaire:
                  type: integer
                  description: |
                    Defines the scope to which the `activityOutsideEu` field applies:
                    * `0` – Not applicable
                    * `1` – Only the legal entity
                    * `2` – The legal entity and all its subsidiaries held at 100%
                    * `3` – The legal entity and all its subsidiaries held at 50% or more
                    * `4` – The legal entity and a list of subsidiaries

                    See the [Sanctions and embargo](/guide/users/legal-entity.html#sanctions-and-embargo) article for more information.
                  enum: [0, 1, 2, 3, 4]
              sanctionsQuestionnaireDate:
                type: string
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                description: Date YYYY-MM-DD HH:mm:ss
                example: "2025-09-15 06:38:46"
                nullable: true
              timezone:
                type: string
                example: "Paris/France"
              occupationType:
                type: string
                description: Deprecated. Use `occupationCategory` instead.
                deprecated: True
                enum:
                  - '' 
                  - 'private_sector_employees'
                  - 'public_sector_employees'
                  - 'retired_people_and_students'
                  - 'self_employed'
                  - 'without_any_professional_activity'
              sourceOfFunds:
                type: string
                description: The source of funds for opening an account for a company or self-employed person
                enum:
                  - ''
                  - 'donation'
                  - 'inheritance'
                  - 'loan' 
                  - 'lottery'
                  - 'pension'
                  - 'proceeds_from_investment'
                  - 'proceeds_from_sale'
                  - 'salary'
                  - 'saving'
              legalSectorType:
                type: string
                description: | 
                  Qualify the type of data in the `legalSector` field 
                    * If it is set to NACE the legalSector needs to be in a NACE format (4 digits). 
                    * If it is set to NAF (or not set at all) the legalSector needs to be in a NAF format (4 digits followed by a capital letter).
                enum:
                  - ''
                  - 'NACE'
                  - 'NAF'
              isOnStockExchange:
                type: integer
                description: |
                  The user is a corporation and is quoted on an organized stock exchange.
                    * `0` – No
                    * `1` – Yes
                enum: [0, 1]
              codeStatus:
                type: string
                description: |
                  See [User Status](/guide/users/introduction.html#user-status-codestatus) for more information.
                enum:
                  - "110005"
                  - "110006"
                  - "110009"
                  - "110012"
              informationStatus:
                type: string
                description: | 
                  Additional information regarding the `codeStatus`, if any.
              createdDate:
                type: string
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                description: | 
                  The date and time at which the User was created.

                  Format: `YYYY-MM-DD HH:mm:ss`
                example: "2025-01-10 15:49:53"
              modifiedDate:
                type: string
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                description: | 
                  The date and time at which the User was last updated.

                  Format: `YYYY-MM-DD HH:mm:ss`
                example: "2025-01-10 15:49:53"
              walletCount:
                type: integer
                description: The number of Wallets owned by the User.
                example: 2
              payinCount:
                type: integer
                description: The number of payins made to this user.
                example: 14
              totalRows:
                type: integer
                description: |
                  The total numbers of objects matching your search, for pagination purposes. Only valued in the first object of the returned page, `null` otherwise.
              occupationCategory:
                type: integer
                nullable: true
                description: |
                  Type of occupation of the user. See [Occupation Category](/guide/users/physical.html#occupation-category-occupationcategory) for the list of values.
                enum: [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]
              personalAssetsRange:
                  type: integer
                  nullable: true
                  description: |
                    The personal assets range of the user. See [Personal Assets Range](/guide/users/physical.html#personal-assets-range-personalassetsrange) for the list of values.
                  enum: [0,1,2,3,4,5,6,7]
              monthlyIncomeRange:
                type: integer
                nullable: true
                description: |
                  Net monthly income of the user. See [Monthly Income Range](/guide/users/physical.html#monthly-income-range-monthlyincomerange) for the list of values.
                enum: [1,2,3,4,5,6,7]
              birthCityCode:
                type: string
                nullable: true
                description: Always set to null.
                example: null
              embed:
                type: object
                nullable: true
                description: |
                  Contains embedded relationship data when the `_embed` query parameter is used. This object is `null` when `_embed` is not specified.

                  See [User Relationships](/guide/users/relationships.html) for more information.
                properties:
                  ascending_relationships:
                    type: object
                    description: Relationships where the user is the target (linked to source entities).
                    properties:
                      meta:
                        type: object
                        properties:
                          page_size:
                            type: integer
                            description: The maximum number of embedded items (fixed at 10).
                            example: 10
                          has_more:
                            type: boolean
                            description: Indicates whether more relationships exist beyond the embedded limit.
                            example: false
                      values:
                        type: array
                        items:
                          $ref: '#/components/schemas/UserRelationShipObject'
                  descending_relationships:
                    type: object
                    description: Relationships where the user is the source (holding relationships to targets).
                    properties:
                      meta:
                        type: object
                        properties:
                          page_size:
                            type: integer
                            description: The maximum number of embedded items (fixed at 10).
                            example: 10
                          has_more:
                            type: boolean
                            description: Indicates whether more relationships exist beyond the embedded limit.
                            example: false
                      values:
                        type: array
                        items:
                          $ref: '#/components/schemas/UserRelationShipObject'
    UserRelationShipObject:
      type: object
      properties:
        relationshipId:
          type: integer
          format: int64
          description: The unique identifier of the relationship.
        targetUserId:
          type: integer
          format: int64
          description: The unique identifier of the target User, linked to the entity.
        sourceUserId:
          type: integer
          format: int64
          description: The unique identifier of the source User; holding the relationship.
        relationshipTypeId:
          type: integer
          description: |
            The type of relationship between the source user and the target user. See the [types of relation](/guide/users/relationships.html#types-of-relation).
          enum: [1,2,3,4,5,6]
        relationshipTypeName:
          type: string
          description: |
            The name of the relationship between the source user and the target user. See the [types of relation](/guide/users/relationships.html#types-of-relation).
          enum:
            - LEGAL_REPRESENTATIVE
            - EFFECTIVE_BENEFICIARY_SHARES
            - COMPANY_REPRESENTATIVE
            - EMPLOYEE
            - CHILD
        value:
          type: string
          nullable: true
          description: |
             Associated value if included with the role (e.g., % of shares for `EFFECTIVE_BENEFICIARY_SHARES`).
    PaginationMetadata:
      type: object
      properties:
        pageNumber:
          type: integer
        pageSize:
          type: integer
        pageAvailable:
          type: integer
        totalCount:
          type: integer

    RelationshipListResponse:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/PaginationMetadata'
        relationships:
          type: array
          items:
            $ref: '#/components/schemas/UserRelationShipObject'
    RelationshipGroupedResponse:
      type: object
      description: Response format when using the `groupBy` parameter.
      properties:
        metadata:
          $ref: '#/components/schemas/PaginationMetadata'
        groups:
          type: array
          description: Array of relationship groups. Each group contains relationships sharing the same value for the `groupBy` field.
          items:
            type: object
            properties:
              targetUserId:
                type: integer
                description: Present when `groupBy=targetUserId` or `groupBy=targetSourcePair`.
              sourceUserId:
                type: integer
                description: Present when `groupBy=sourceUserId` or `groupBy=targetSourcePair`.
              relationships:
                type: array
                items:
                  $ref: '#/components/schemas/UserRelationShipObject'
    VirtualIbanObject:
      type: object
      properties:
        virtualibans:
          type: array
          items:
            type: object
            properties:
              virtualibanId:
                type: integer
                description: The unique identifier of the Virtual IBAN.
              walletId:
                type: integer
                description: The unique identifier of the Wallet to which the Virtual IBAN is associated.
              typeId:
                type: integer
                description: The type of the Virtual IBAN.
                enum: [1, 2]
              tag:
                type: string
                maxLength: 250
                description: |
                  Custom attribute that you can use as you see fit.
            
                  Learn more in the [Object tags](/guide/api-basics/objects-tags.html) article.          
              reference: 
                type: string
                description: The client's internal reference of the Virtual IBAN.
              validFrom:
                type: string
                format: date
                description: |
                  The date from which the Virtual IBAN validity starts. Defaults to today's date and must be set in the future.

                  Format: `YYYY-MM-DD`
                example: "2025-01-01"
              validTo:
                type: string
                format: date
                description: |
                  The date from which the Virtual IBAN validity ends. Must be set after the `validFrom` date.

                  Format: `YYYY-MM-DD`
                example: "2025-01-01"
              maxUsage:
                type: integer
                description: The maximum number of transactions allowed.
                example: 5
              maxAmount:
                type: string
                format: float
                description: The maximum cumulated amount allowed.
                example: "23.99"
              iban:
                type: string
                description: The IBAN of the virtual IBAN.
                example: "FR7616798000010000071474474"
              createdDate:
                type: string
                description: | 
                  The date and time at which the Virtual IBAN was created.
                  
                  Format: `YYYY-MM-DD HH:mm:ss`
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                example: "2025-01-10 15:49:53"
              numberOfTransactions:
                type: integer
                description: The current number of transactions for the Virtual IBAN.
                example: 3
              cumulatedAmount:
                type: string
                format: float
                description: The cumulated amount of transactions for the Virtual IBAN.
                example: "1000.00"
              updatedDate:
                type: string
                description: | 
                  The date and time at which the Virtual IBAN was last updated.
                  
                  Format: `YYYY-MM-DD HH:mm:ss`
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                example: "2025-01-10 15:49:53"
    statementCardPayment:
      type: object
      properties:
        paymentId:
          type: string
          description: |
            The unique identifier of the card payment (or attempted payment), allowing you to follow the card transaction life cycle.
          example: "345UIH987"
        publicToken:
          type: string
          description: | 
            The token of the card. This is a way to identify a card without knowing or communicating its [PAN](/guide/overview/glossary#primary-account-number-pan).
          example: "107688667"
        maskedPan:
          type: string
          description: |
            Partially hidden card number.
          example: "****9997"
        merchantName:
          type: string
          description: The name of the merchant. 
          example: "Tree Cie"
        localAmount:
          type: object
          properties:
            amount:
              type: integer
              format: int64
              description: The amount expressed in cents.
              example: 12000
            currency:
              type: string
              description: The local currency in which the transaction was made, ISO 4217 3-letter code.
              format: ISO 4217
              example: "978"
        userId:
          type: string
          description: The unique identifier of the cardholder.
    statementPayin:
      type: object
      properties:
        payinId:
          type: string
          description: The unique identifier of the payin.
          example: "2072680217"
        payinTag:
          type: string
          nullable: true
          example: "PT-Eos sequi ut"
        label:
          type: string
          nullable: true
          example: "account closure"
        ibanFullname:
          type: string
          nullable: true
          example: "Alex Oak"
        ibanBic:
          type: string
          nullable: true
          example: "TREEZORRPPXXX"
        dbtrIBAN:
          type: string
          nullable: true
          example: "FR901009600XXX4563723173X10"
        ibanTxEndToEndId:
          type: string
          nullable: true
          example: "987"
        mandateId:
          type: string
          nullable: true
          example: "12"
        debtorName:
          type: string
          nullable: true
          example: "Alex Oak"
        uniqueMandateReference:
          type: string
          description: |
            The unique reference that unambiguiously identify a mandate signed between the user and the beneficiary. 
                          
            See the [Unique Mandate Reference (UMR)](/guide/overview/glossary.html#unique-mandate-reference-umr) article for more information.
          nullable: true
          example: "127b8a5a-ab33-3bb5-a2dc-f5f5d1e14db1"
        additionalData:
          type: array
          nullable: true
          items:
            type: string
    statementPayinRefund:
      type: object
      properties:
        payinRefundId:
          type: string
          example: "8798"
        payinId:
          type: string
          nullable: true
          example: "35654"
        payinTag:
          type: string
          nullable: true
          example: "NOT PROVIDED"
        label:
          type: string
          nullable: true
          example: "Account closure"
        ibanFullname:
          type: string
          nullable: true
          example: "Alex Oak"
        dbtrIBAN:
          type: string
          nullable: true
          example: "FR9010096000404563723173G10"
        debtorName:
          type: string
          nullable: true
          example: "Alex Oak"
        uniqueMandateReference:
          type: string
          description: |
            The unique reference that unambiguiously identify a mandate signed between the user and the beneficiary. 
                          
            See the [Unique Mandate Reference (UMR)](/guide/overview/glossary.html#unique-mandate-reference-umr) article for more information.
          nullable: true
          example: "127b8a5a-ab33-3bb5-a2dc-f5f5d1e14db1"
        ibanBic:
          type: string
          nullable: true
          example: "TREEZORRPPXXX"
        additionalData:
          type: array
          nullable: true
          items:
            type: string
    statementPayout:
      type: object
      properties:
        payoutId:
          type: string
          description: The unique identifier of the payout.
          example: "34567890"
        payoutTag:
          type: string
          maxLength: 250
          nullable: true
          example: "6ab2947d-58c2-4450-b235-54b62556eee9@e6572b3c-53e5-425d-bff2-ccba90b806f7"
        label:
          type: string
          nullable: true
          example: "Account closure"
        beneficiaryId:
          type: string
          example: "34567890"
        beneficiaryName:
          type: string
          nullable: true
          example: "Willow"
        endToEndId:
          type: string
          nullable: true
          example: "987"
        reasonCode:
          type: string
          nullable: true
          example: "09"
        reasonDescription:
          type: string
          nullable: true
        uniqueMandateReference:
          type: string
          description: |
            The unique reference that unambiguiously identify a mandate signed between the user and the beneficiary. 
                          
            See the [Unique Mandate Reference (UMR)](/guide/overview/glossary.html#unique-mandate-reference-umr) article for more information.
          nullable: true
          example: "127b8a5a-ab33-3bb5-a2dc-f5f5d1e14db1"
    statementPayoutRefund:
      type: object
      properties:
        payoutRefundId:
          type: string
          example: "8765456789"
        payoutId:
          type: string
          nullable: true
          example: "3456789"
        payoutTag:
          type: string
          maxLength: 250
          nullable: true
          example: "6ab2947d-58c2-4450-b235-54b62556eee9@e6572b3c-53e5-425d-bff2-ccba90b806f7"
        label:
          type: string
          nullable: true
          example: "Account closure"
        beneficiaryId:
          type: string
          example: "345987"
        beneficiaryName:
          type: string
          nullable: true
          example: "Alex Oak"
        endToEndId:
          type: string
          nullable: true
          example: "456789"
        reasonCode:
          type: string
          nullable: true
          example: "09"
        reasonDescription:
          type: string
          nullable: true
          example: "Transaction forbidden on this type of account"
        uniqueMandateReference:
          type: string
          description: 
            The unique reference that unambiguiously identify a mandate signed between the user and the beneficiary. 
                          
            See the [Unique Mandate Reference (UMR)](/guide/overview/glossary.html#unique-mandate-reference-umr) article for more information.
          nullable: true
          example: "127b8a5a-ab33-3bb5-a2dc-f5f5d1e14db1"
    statementTransfer:
      type: object
      properties:
        transferId:
          type: string
          example: "456789"
        transferTag:
          type: string
          example: "2335046_10_2335047_2024-07-05"
          nullable: true
        label:
          type: string
          nullable: true
          example: "Account closure"
        creditorFirstName:
          type: string
          example: "Alex"
        creditorLastName:
          type: string
          example: "Oak"
        creditorLegalName:
          type: string
          example: "Tree Cie"
        debtorWalletId:
          type: string
          example: "34567"
        debtorFirstName:
          type: string
          example: "Chris"
        debtorLastName:
          type: string
          example: "Willow"
        debtorLegalName:
          type: string
          example: "Tree Cie"
    CardTransactionObject:
      type: object
      properties:
        cardtransactionId:
          type: string
          description: The unique identifier of the Card Transaction.
          example: "12345"
        cardId:
          type: string
          description: The unique identifier of the card used for the transaction.
          example: "12345"
        walletId:
          type: string
          description: The unique identifier of the Wallet the card is attached to.
          example: "12345" 
        acquirerId:
          type: string
          description: The identifier of the merchant's bank (acquirer) in the form of 5 to 6 digits.
          example: "666666"
        walletCurrency:
          type: string
          format: ISO 4217 3-digit code
          description: The currency of the Wallet the card is attached to.
          example: "978"
        merchantId:
          type: string
          description: |
            The [Merchant Identifier Number (MID)](/guide/overview/glossary#merchant-identifier-number-mid).
        merchantName:
          type: string
          description: The name of the merchant.
        merchantCity:
          type: string
          description: The address city of the merchant.
        merchantCountry:
          type: string
          format: ISO 3166
          description: | 
            The address country of the merchant. ISO 3166 3-letter code (except of the US which is a two-letter code)
          example: "FRA"
        mccCode:
          type: string
          description: | 
            The [Merchant Category Code (MCC)](/guide/overview/glossary#merchant-category-code-mcc). A MCC valued to `6011` indicates a withdrawal.
            
            Some MCC are prohibited for [anonymous electronic money](/guide/wallets/introduction#electronic-money-wallet-type-9), such as: money transfer, money order, foreign currency, liquid and cryptocurrency assets, lotteries, on-line gambling, betting, etc.
          example: "5812"
        paymentLocalTime:
          type: string
          # pattern: '^\d{2}[0-5]\d[0-5]\d$'
          description: |
            The local time at which the transaction occurred.

            Format: `HHmmss` (24-hour format, e.g., `235959` for 23:59:59).
          example: "235959"
        publicToken:
          type: string
          description: | 
            The token of the card. This is a way to identify a card without knowing or communicating its [PAN](/guide/overview/glossary#primary-account-number-pan).
          example: "107688667"
        paymentAmount:
          type: string
          format: float
          description: | 
            The amount of the transaction, always expressed in Euros. See the `paymentLocalAmount` for the value in the payment local currency.
          example: "11.90"
        paymentCurrency:
          type: string
          format: ISO 4217
          description: |
            The currency of the payment. Format: [ISO 4217](/guide/api-basics/data-format.html#currencies) 3-digit code.
          example: "978"
        fees:
          type: string
          description: ATM usage or foreign payments fees as defined by Treezor, always set to `0`.
          example: "0"
        paymentCountry:
          type: string
          format: ISO 3166
          description: Country in which the transaction occurred, ISO 3166 3-letter code.
          example: "FRA"
        paymentId:
          type: string
          description: |
            The unique identifier of the card payment (or attempted payment), allowing you to follow the card transaction life cycle.
        paymentStatus:
          type: string
          description: |
            The status of the payment. See the [Statuses](/guide/cards/transactions.html#statuses-paymentstatus) article for more information.
          enum: ["A","C","I","M","R","S","V"]
        paymentLocalAmount:
          type: string
          format: float
          description: The amount of the transaction in the local currency.
          example: "12.80"
        posCardholderPresence:
          type: string
          description: |
            Indicates whether the cardholder was physically present, and if not, how they ordered the card transaction.
            
            See [Cardholder Presence](/guide/cards/transactions.html#cardholder-presence-poscardholderpresence) for more information.
          enum: ["0","1","2","3","4","5","6","9"]
        posPostcode:
          type: string
          description: Postcode of the point of sale where the transaction occurred.
        posCountry:
          type: string
          format: ISO 3166
          description: Country of the point of sale where the transaction occurred, in ISO 3166 3-digit code format.
          example: "250"
        posTerminalId:
          type: string
          description: The identifier of the terminal used for the transaction.
          example: "B1234567"
          minLength: 1
          maxLength: 8
        posCardPresence:
          type: string
          description: |
            Indicates whether the card was physically present during the transaction: 
            * `0` – The card was present.
            * `1` – The card was absent.
            * `9` – The card presence cannot be determined.
          enum: ["0","1","9"]
        panEntryMethod:
          type: string
          description: |
            Indicates how the merchant captured the [PAN](/guide/overview/glossary.html#primary-account-number-pan). See [PAN Entry Method](/guide/cards/transactions.html#pan-entry-method-panentrymethod) for more information.
          enum: ["0","1","2","3","4","5","7","10","79","80","81","91"]
        authorizationNote:
          type: string
          description: |
            Information regarding the cause of a payment incident and/or status. 
            
            See [Authorization Notes](/guide/cards/authorization-notes.html#authorization-response-codes) for more information and a list of common examples.
          maxLength: 256
          example: "DR: Card not found UnKnownCard"
        authorizationResponseCode:
          type: string
          description: |
            Response code for a given card transaction, providing additional information regarding as to why a transaction was accepted or refused.

            See [Authorization Codes](/guide/cards/authorization-notes.html#authorization-response-codes) for more information.
          example: "10"
        authorizationIssuerId:
          type: string
          description: The transaction identifier as generated by the payment processor.
        authorizationIssuerTime:
          type: string
          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
          description: | 
            The date and time at which the payment processor authorized the transaction. This value is based on the processor's timezone (Europe/London).

            Format: `YYYY-MM-DD HH:mm:ss`
          example: "2025-02-12 13:00:00"
        authorizationMti:
          type: string
          description: |
            Authorization Message Type Identifier. Please rely on the `paymentStatus` value.
          example: "100"
        authorizedBalance:
          type: string
          format: float
          description: | 
            The [Authorized Balance](/guide/wallets/balances.html) of the wallet after the transaction.
          example: "345.88"
        limitAtmYear:
          type: string
          description: | 
            The ATM operations limit of the corresponding card for a sliding year.

            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
          example: "0"
        limitAtmMonth:
          type: string
          description: | 
            ATM operations limit of the corresponding card for a sliding month.

            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
          example: "0"
        limitAtmWeek:
          type: string
          description: | 
            ATM operations limit of the corresponding card for a sliding week.

            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
          example: "2000"
        limitAtmDay:
          type: string
          description: | 
            ATM operations limit of the corresponding card for a single day.

            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
          example: "1000"
        limitAtmAll:
          type: string
          description: | 
            ATM operations limit of the corresponding card from beginning.

            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
          example: "0"
        limitPaymentYear:
          type: string
          description: |
            POS operations limit of the corresponding card for a sliding year.

            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
          example: "0"
        limitPaymentMonth:
          type: string
          description: | 
            POS operations limit of the corresponding card for a sliding month.

            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
          example: "0"
        limitPaymentWeek:
          type: string
          description: | 
            POS operations limit of the corresponding card for a sliding week.

            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
          example: "3000"
        limitPaymentDay:
          type: string
          description: | 
            POS operations limit of the corresponding card for a single day.

            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
          example: "2000"
        limitPaymentAll:
          type: string
          description: |
            POS operations limit of the corresponding card from beginning.

            See [Payment & Withdrawal limits](/guide/cards/restrictions-limits.html#payment-withdrawal-limits) for more information.
          example: "0"
        totalLimitAtmYear:
          type: string
          format: float
          description: The card yearly withdrawal amount.
          example: "0.00"
        totalLimitAtmMonth:
          type: string
          format: float
          description: The card monthly withdrawal amount.
          example: "0.00"
        totalLimitAtmWeek:
          type: string
          description: The card weekly withdrawal amount.
          format: float
          example: "0.00"
        totalLimitAtmDay:
          type: string
          format: float
          description: The card daily withdrawal amount.
          example: "0.00"
        totalLimitAtmAll:
          type: string
          format: float
          description: The card total withdrawal amount.
          example: "0.00"
        totalLimitPaymentYear:
          type: string
          format: float
          description: The card yearly spent amount.
          example: "0.00"
        totalLimitPaymentMonth:
          type: string
          format: float
          description: The card monthly spent amount.
          example: "0.00"
        totalLimitPaymentWeek:
          type: string
          format: float
          description: The card weekly spent amount.
          example: "0.00"
        totalLimitPaymentDay:
          type: string
          format: float
          description: The card daily spent amount.
          example: "0.00"
        totalLimitPaymentAll:
          type: string
          format: float
          description: The card total spent amount.
          example: "0.00"
        paymentDailyLimit:
          type: string
          nullable: true
          format: float
          description: The daily payment limit.
          example: "0.00"
        cardDigitalizationExternalId:
          type: string
          nullable: true
          description: |
            The digital payment token identifier (only present if payment was made with a digital token such as Apple Pay or Google Pay for example).
        is3DS:
          type: integer
          nullable: true
          description: |
            Indicates whether [3DSecure](/guide/overview/glossary#_3ds-3d-secure) was used for authentication:
            * `0` – 3DS was not used
            * `1` – 3DS was used
          enum: [0,1]
        merchantAddress:
          type: string
          nullable: true
          description: The address of the merchant.
        paymentLocalDate:
          type: string
          nullable: true
          description: | 
            The local date on which the transaction occurred.

            Format: `YYYYMMDD` (e.g., `20251228` for December 28, 2025)
          example: "20251228"
        totalRows:
          type: string
          description: |
            The total numbers of objects matching your search, for pagination purposes.
        optimizedMerchantName:
          type: string
          maxLength: 50
          description: The name of the merchant, optimized for display and understanding.
          example: "Merchant's Name"
          nullable: true
        merchantLogo:
          type: string
          format: uri
          description: The URL's of the merchant's logo.
          example: "https://storage.googleapis.com/merchantlogo.png"
          nullable: true
        merchantCategory:
          type: string
          description: The category of the merchant. Value may be displayed in the cardholder's language if available.
          example: "Retail & Shopping"
          nullable: true
          enum:
            - "Bills, Fees & Services"
            - "Cash & Banking"
            - "Charity & Donations"
            - "Cultural & Education"
            - "Eating Out"
            - "Entertainment & Recreation"
            - "Groceries & Supermarkets"
            - "Health & Wellness"
            - "Home & Family"
            - "Other"
            - "Retail & Shopping"
            - "Transportation & Mobility"
            - "Travel & Holidays"
        transactionSubtype:
          type: string
          description: |
            Additional information regarding the type of card transaction. Values can be:
              * `OFT` – Offline transaction
              * `PRE` – Preauthorization
              * `SEP` – Second presentment
          enum:
            - OFT
            - PRE
            - SEP
        3dsExemptionType:
          type: string
          deprecated: true
          description: | 
            Deprecated. See `exemptionType3ds`.
          example: "2"
        exemptionType3ds:
          type: string
          description: | 
            Indicates why the transaction was exempted for 3DS authentication. See [3DS Exemption Type](/guide/cards/transactions.html#_3ds-exemption-type-exemptiontype3ds) for the value list.
          example: "2"
        receiverData:
          type: string
          description: |
            For MoneySend transactions, information regarding the receiver. It usually includes details such as the receiver's name, masked pan, and address, separated by digits.
          example: "0104Alex0303Oak0411Main Street0510Willow Lane0703USA"
        senderData:
          type: string
          description: | 
            For MoneySend transactions, information regarding the sender. It usually includes details such as the sender's name, masked pan, and address, separated by digits.
          example: "0104Alex0303Oak0411Main Street0510Willow Lane0703USA"
        transactionTypeIdentifier:
          type: string
          description: | 
            For MoneySend transactions, code indicating the type of transaction and the source of funds. Can be:
              * `C07` – Person-to-Person Transfer
              * `C52` – General Transfer to Own Account
              * `C53` – Agent Cash Out
              * `C54` – Payment of Own Credit Card Bill
              * `C55` – Business Disbursement
              * `C56` – Government/Non-profit Disbursement
              * `C57` – Rapid Merchant Settlement
              * `C59` – Cash-in at Point of Sale
              * `C65` – General Business-to-Business Transfer
          enum: ["C07","C52","C53","C54","C55","C56","C57","C59","C65"]
        localMerchantId:
          type: string
          description: Indicates the merchant's SIREN or SIRET if available.
        merchantCategoryGroup:
          type: string
          description: | 
            Sub-group of the category defined in `merchantCategory`. Value may be displayed in the cardholder's language if available.
          nullable: true
          example: "Retail & Department Stores"
        merchantCategoryType:
          type: string
          description: |
            Precise type of the sub-group defined in `merchantCategoryGroup`. Value may be displayed in the cardholder's language if available.
          nullable: true
          example: "Furniture"
        authorizationIdResponse:
          type: string
          description: A unique identifier generated by the issuing institution during a transaction. 
          example: "560268"
          nullable: true
        isPinValidated:
          type: boolean
          description: Whether the PIN was entered and successfully verified.
          nullable: true
    CardPayment:
      type: object
      properties:
        mcc:
          type: object
          properties:
            code:
              type: integer
              format: int64
        mid:
          type: object
          properties:
            value:
              type: string
            name:
              type: string
            city:
              type: string
              nullable: true
            country:
              type: string
              nullable: true
            address:
              type: string
              nullable: true
            paymentCountry:
              type: string
              nullable: true
              # to review
        localAmount:
          type: object
          properties:
            amount:
              type: integer
              format: int64
              description: Amount in cents
              example: 12000
            currency:
              type: string
              description: Currency in ISO-4217
              example: "978"
        authorisationResponseCode:
          type: object
          properties:
            action:
              type: string
            description:
              type: string
            value:
              type: integer
              nullable: true
        paymentLifeCycle:
          type: array
          items:
            $ref: '#/components/schemas/PaymentLifeCycle'
        paymentCountry:
          type: string
          nullable: true
        cardId:
          type: string
        userId: 
          type: string
          description: The unique identifier of the cardholder (the User who owns the card).
        paymentId:
          type: string
          description: The unique identifier of the card transaction payment.
        embossedName:
          type: string
          description: The cardholder name embossed on the card.
          example: "ALEX OAK"
        publicToken:
          type: string
        maskedPan:
          type: string
        isPinValidated:
          type: boolean
        is3DS:
          type: string
          nullable: true
        exemptionType3ds:
          type: string
          nullable: true
          description: | 
            Indicates why the transaction was exempted for 3DS authentication. See [3DS Exemption Type](/guide/cards/transactions.html#_3ds-exemption-type-exemptiontype3ds) for the value list.
        optimizedMerchantName:
          type: string
          maxLength: 50
          description: The name of the merchant, optimized for display and understanding.
          example: "Merchant's Name"
          nullable: true
        merchantLogo:
          type: string
          format: uri
          nullable: true
          description: The URL's of the merchant's logo.
          example: "https://storage.googleapis.com/merchantlogo.png"
        merchantCategory:
          type: string
          description: |
            The category of the merchant. Value may be displayed in the cardholder's language if available.
          example: "Retail & Shopping"
          nullable: true
          enum:
            - "Bills, Fees & Services"
            - "Cash & Banking"
            - "Charity & Donations"
            - "Cultural & Education"
            - "Eating Out"
            - "Entertainment & Recreation"
            - "Groceries & Supermarkets"
            - "Health & Wellness"
            - "Home & Family"
            - "Other"
            - "Retail & Shopping"
            - "Transportation & Mobility"
            - "Travel & Holidays"
        merchantCategoryGroup:
          type: string
          description: |
            Sub-group of the category defined in `merchantCategory`. Value may be displayed in the cardholder's language if available.
          nullable: true
          example: "Retail & Department Stores"
        merchantCategoryType:
          type: string
          description: |
            Precise type of the sub-group defined in `merchantCategoryGroup`. Value may be displayed in the cardholder's language if available.
          nullable: true
          example: "Furniture"
        transactionSubtype:
          type: string
          description: |
            Additional information regarding the type of card transaction. Values can be:
              * `OFT` – Offline transaction
              * `PRE` – Preauthorization
              * `SEP` – Second presentment
          nullable: true
        authorizationNote:
          type: string
          maxLength: 256
    PaymentLifeCycle:
      type: object
      properties:
        authorizationIssuerTime:
          type: string
          description: | 
            The date and time at which the payment processor authorized the transaction. This value is based on the processor's timezone (Europe/London).

            Format: `YYYY-MM-DD HH:mm:ss`
          example: "2025-02-12 13:00:00"
        valueDate:
          type: string
          nullable: true
        paymentAmount:
          type: string
        paymentLocalAmount:
          type: string
        paymentCurrency:
          type: string      
    Chargeback:
      type: object
      properties:
        payinId:
          type: string
          nullable: false
        payinRefundId:
          type: string
          nullable: false
        transactionReference:
          type: string
          nullable: false
        payinTag:
          type: string
          nullable: true
        additionalData:
          type: array
          items:
            type: string
        chargebackReason:
          type: string
    Payin:
      type: object
      properties:
        messageToUser:
          type: string
          nullable: true
        codeStatus:
          type: string
          nullable: false
        informationStatus:
          type: string
          nullable: true
        paymentMethodId:
          type: integer
          description: |
            The type of payin.

            | Id | Payment by |
            | ---| --- |
            | `20` | [Received SEPA Credit Transfer (SCTR)](/guide/transfers/credit-transfer.html#received-credit-transfers-sctr). You can only create such payins in Sandbox, otherwise created automatically upon receiving a transfer. |
            | `21` | [Emitted SEPA Core Direct Debit (SDDE Core)](/guide/transfers/direct-debit.html#emitted-direct-debits-sdde). |
            | `22` | [Emitted SEPA B2B Direct Debit (SDDE B2B)](/guide/transfers/direct-debit.html#emitted-direct-debits-sdde). |
            | `23` | **Deprecated** (Full Hosted HTML Payment Form). |
            | `24` | **Deprecated** (IFrame Payment Form). |
            | `25` | [Card topups](/guide/acquiring/introduction.html). You cannot create a payin directly with this method id. The payin will be automatically created by Treezor. |
            | `26` | [Check cashing](/guide/cheques/introduction.html) |
            | `27` | [Received SEPA Instant Credit Transfer](/guide/transfers/credit-transfer-inst.html#received-instant-credit-transfers-sctr-inst). You cannot create a payin directly with this method id. The payin will be automatically created by Treezor. |
            | `28` | [Received International Transfer](/guide/transfers/international.html#received-international-transfers). You cannot create a payin directly with this method id. The payin will be automatically created by Treezor. |
          enum: [20, 21, 22, 23, 24, 25, 26, 27, 28]
        payinTag:
          type: string
          nullable: true
        additionalData:
          type: array
          nullable: true
          items:
            type: string
        ibanFullname:
          type: string
          nullable: true
        ibanBic:
          type: string
          nullable: true
        dbtrIBAN:
          type: string
          nullable: true
        mandateId:
          type: string
          nullable: true
        ibanTxEndToEndId:
          type: string
          nullable: true
        payinId:
          type: string
        debtorName:
          type: string
          nullable: true
        uniqueMandateReference:
          type: string
          description: |
            The unique reference that unambiguiously identify a mandate signed between the user and the beneficiary. 
                          
            See the [Unique Mandate Reference (UMR)](/guide/overview/glossary.html#unique-mandate-reference-umr) article for more information.
          nullable: true
    PayinObject:
      type: object
      properties:
        payins:
          type: array
          items:
            type: object
            properties:
              payinId:
                type: string
                description: |
                  The unique identifier of the payin. In the specific case of the SCTR Inst payin, this value is a uuid.
              payinTag:
                type: string
                maxLength: 250
                description: |
                    Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
                    
                    Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
              payinStatus:
                type: string
                description: |
                  The status of the payin. See [Payin statuses](/guide/transfers/introduction.html#payin-statuses-codestatus) for more information.
                enum:
                  - CANCELED
                  - PENDING
                  - VALIDATED
              codeStatus:
                type: string
                description: |
                  The code for the status of the payin. See [Payin statuses](/guide/transfers/introduction.html#payin-statuses-codestatus) for more information.
                enum: ["140001", "140004", "140005", "140006", "140007", "140010"]
              informationStatus:
                type: string
                description: Additional information regarding the status (if any).
                example: "Awaiting confirmation"
              walletId:
                type: string
                description: The unique identifier of the wallet.
                example: "2162136"
              userId:
                type: string
                description: The unique identifier of the user.
                example: "3400118"
              cartId:
                type: integer
                deprecated: true
                nullable: true
              walletEventName:
                type: string
                description: The name of the Wallet.
                example: "Main account"
              walletAlias:
                type: string
                deprecated: true
              userFirstname:
                type: string
                description: The first name of the user owning the Wallet.
                example: "Alex"
              userLastname:
                type: string
                description: The last name of the user owning the Wallet.
                example: "Oak"
              messageToUser:
                type: string
                description:
                  Message to send to Wallet of the user. For SEPA Direct Debit Core payment method, this parameter reconciles information transmitted to the Debtor (i.e., Invoice number). In this case, it can't exceed 140 characters.
                example: "Monthly subscription payment"
              paymentMethodId:
                type: string
                description: |
                  The type of payin.

                  | Id | Payment by |
                  | ---| --- |
                  | `20` | [Received SEPA Credit Transfer (SCTR)](/guide/transfers/credit-transfer.html#received-credit-transfers-sctr). You can only create such payins in Sandbox, otherwise created automatically upon receiving a transfer. |
                  | `21` | [Emitted SEPA Core Direct Debit (SDDE Core)](/guide/transfers/direct-debit.html#emitted-direct-debits-sdde). |
                  | `22` | [Emitted SEPA B2B Direct Debit (SDDE B2B)](/guide/transfers/direct-debit.html#emitted-direct-debits-sdde). |
                  | `23` | **Deprecated** (Full Hosted HTML Payment Form). |
                  | `24` | **Deprecated** (IFrame Payment Form). |
                  | `25` | [Card topups](/guide/acquiring/introduction.html). You cannot create a payin directly with this method id. The payin will be automatically created by Treezor. |
                  | `26` | [Check cashing](/guide/cheques/introduction.html) |
                  | `27` | [Received SEPA Instant Credit Transfer](/guide/transfers/credit-transfer-inst.html#received-instant-credit-transfers-sctr-inst). You cannot create a payin directly with this method id. The payin will be automatically created by Treezor. |
                  | `28` | [Received International Transfer](/guide/transfers/international.html#received-international-transfers). You cannot create a payin directly with this method id. The payin will be automatically created by Treezor. |
                enum: ["20", "21", "22", "23", "24", "25", "26", "27", "28"]
              subtotalItems:
                type: string
                deprecated: true
              subtotalServices:
                type: string
                deprecated: true
              subtotalTax:
                type: string
                deprecated: true
              amount:
                type: string
                description: The amount of the payin. Decimal number.
                example: "25.64"
              currency:
                type: string
                format: ISO 4217
                description: |
                  The currency of the payin in [ISO 4217](/guide/api-basics/data-format.html#currencies) format. Must be the same as the Wallet currency.
                example: "EUR"
              distributorFee:
                type: string
                deprecated: true
                nullable: true
              createdDate:
                type: string
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                description: |
                  The date and time at which the payin was created.
                  
                  Format: `YYYY-MM-DD HH:mm:ss`
                example: "2025-01-10 15:49:53"
              createdIp:
                type: string
                description: The IP address of the User.
                nullable: true
              paymentHtml:
                type: string
                nullable: true
              paymentLanguage:
                type: string
                nullable: true
              paymentPostUrl:
                type: string
                nullable: true
              paymentPostDataUrl:
                type: string
                nullable: true
              paymentAcceptedUrl:
                type: string
                nullable: true
              paymentWaitingUrl:
                type: string
                nullable: true
              paymentRefusedUrl:
                type: string
                nullable: true
              paymentCanceledUrl:
                type: string
                nullable: true
              paymentExceptionUrl:
                type: string
                nullable: true
              ibanFullname:
                type: string
                nullable: true
              ibanId:
                type: string
                example: "8e5522e9ccd084d54ef7b897af495cad55ca617c"
              ibanBic:
                type: string
                description: |
                  The [BIC](/guide/overview/glossary#bank-identifier-code-bic) of the account crediting the wallet.

                  In the specific case of [International Transfer](/guide/transfers/international.html), concatenation of the type of bank code and its value. Example: BIC-CMCIFRPAXXX
                example: "TRZOFR21XXX"
                nullable: true
              ibanTxEndToEndId:
                type: string
                nullable: true
              ibanTxId:
                type: string
                nullable: true
              refundAmount:
                type: string
                example: "0.00"
              totalRows:
                type: integer
                description: |
                  The total numbers of objects matching your search, for pagination purposes. Only valued in the first object of the returned page, `null` otherwise.
                example: 148
              forwardUrl:
                type: string
                example: "https://example.com/payment/callback"
              payinDate:
                type: string
                description: |
                  The date at which the SDD should be presented. 
                  
                  In the case of SDD Core, this parameter defaults to the third working day following the payin creation if left empty. 
                  
                  Format: `YYYY-MM-DD`, a [SEPA Open Banking Day](/guide/overview/glossary.html#sepa-open-banking-days) is expected, based on the rules described in the [dedicated article](/guide/transfers/direct-debit.html#parameters).
                example: "2025-05-18"
              mandateId:
                type: integer
                description: The unique identifier of the Mandate. This parameter is mandatory when performing a payin with method SDD Core.
                example: 1123456
              creditorName:
                type: string
                example: "Tree Company"
              creditorAddressLine:
                type: string
                example: "15 Rosewood lane, 75017 Paris"
              creditorCountry:
                type: string
                example: "FR"
              creditorIban:
                type: string
                example: "FR763000200045300001023XX32"
              creditorBIC:
                type: string
                example: "TREEFRXXX"
              virtualIbanId:
                type: integer
                example: 123654
              virtualIbanReference:
                type: string
                example: "TRZ-VIBAN-001"
              DbtrIBAN:
                type: string
                example: "FR7612345987650123456789014"
              additionalData:
                oneOf:
                  - type: array
                    items:
                      type: string
                  - type: string
                description: Additional data related to the payin. Can be an array or a string.
    PayinRefund:
      type: object
      properties:
        payinId:
          type: string
          nullable: true
        codeStatus:
          type: string
          nullable: true
        informationStatus:
          type: string
          nullable: true
        paymentMethodId:
          type: integer
          description: |
            The type of payin.

            | Id | Payment by |
            | ---| --- |
            | `20` | [Received SEPA Credit Transfer (SCTR)](/guide/transfers/credit-transfer.html#received-credit-transfers-sctr). You can only create such payins in Sandbox, otherwise created automatically upon receiving a transfer. |
            | `21` | [Emitted SEPA Core Direct Debit (SDDE Core)](/guide/transfers/direct-debit.html#emitted-direct-debits-sdde). |
            | `22` | [Emitted SEPA B2B Direct Debit (SDDE B2B)](/guide/transfers/direct-debit.html#emitted-direct-debits-sdde). |
            | `23` | **Deprecated** (Full Hosted HTML Payment Form). |
            | `24` | **Deprecated** (IFrame Payment Form). |
            | `25` | [Card topups](/guide/acquiring/introduction.html). You cannot create a payin directly with this method id. The payin will be automatically created by Treezor. |
            | `26` | [Check cashing](/guide/cheques/introduction.html) |
            | `27` | [Received SEPA Instant Credit Transfer](/guide/transfers/credit-transfer-inst.html#received-instant-credit-transfers-sctr-inst). You cannot create a payin directly with this method id. The payin will be automatically created by Treezor. |
            | `28` | [Received International Transfer](/guide/transfers/international.html#received-international-transfers). You cannot create a payin directly with this method id. The payin will be automatically created by Treezor. |
          enum: [20, 21, 22, 23, 24, 25, 26, 27, 28]
        reasonTms:
          type: string
          nullable: true
        payinTag:
          type: string
          nullable: true
        messageToUser:
          type: string
          nullable: true
        ibanFullName:
          type: string
          nullable: true
        ibanBic:
          type: string
          nullable: true
        dbtrIBAN:
          type: string
          nullable: true
        ibanTxEndToEndId:
          type: string
          nullable: true
        mandateId:
          type: string
          nullable: true
        debtorName:
          type: string
          nullable: true
        uniqueMandateReference:
          type: string
          description: |
            The unique reference that unambiguiously identify a mandate signed between the user and the beneficiary. 
                          
            See the [Unique Mandate Reference (UMR)](/guide/overview/glossary.html#unique-mandate-reference-umr) article for more information.
          nullable: true
        additionalData:
          type: array
          items:
            type: string
    Payout:
      type: object
      properties:
        payoutTag:
          type: string
          maxLength: 250
          nullable: true
        beneficiaryId:
          type: string
          nullable: false
        label:
          type: string
          nullable: true
        codeStatus:
          type: string
          nullable: false
        informationStatus:
          type: string
          nullable: true
        payoutTypeId:
          type: integer
          enum: [1,2,3,4]
          nullable: true
        uniqueMandateReference:
          type: string
          description: |
            The unique reference that unambiguiously identify a mandate signed between the user and the beneficiary. 
                          
            See the [Unique Mandate Reference (UMR)](/guide/overview/glossary.html#unique-mandate-reference-umr) article for more information.
          nullable: true
        supportingFileLink:
          type: string
          nullable: true
        endToEndId:
          type: string
          nullable: true
        reasonCode:
          type: string
          nullable: true
        reasonDescription:
          type: string
          nullable: true
        beneficiaryName:
          type: string
          nullable: true
    PayoutObject:
      type: object
      properties:
        payouts:
          type: array
          items:
            type: object
            properties:
              payoutId:
                type: integer
                description: The unique identifier of the payout.
                example: 12345
              payoutTag:
                type: string
                maxLength: 250
                description: |
                  Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.

                  Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
              payoutStatus:
                type: string
                description: The status of the payout.
                enum:
                  - CANCELED
                  - PENDING
                  - VALIDATED
              payoutTypeId:
                type: integer
                description: |
                  The type of payout among the following:
                  * `1` for SEPA Credit Transfer (default)
                  * `2` for SEPA Direct Debit
                  * `3` for SEPA Instant Credit Transfer
                  * `4` for International Transfer
                enum: [1,2,3,4]
              payoutType:
                type: string
                enum:
                  - Credit Transfer
                  - Direct Debit
                  - Sepa Instant Credit Transfer
              walletId:
                type: integer
                description: The unique identifier of the wallet being debited.
              payoutDate:
                type: string
                format: date
                description: |
                  The date of the payout. Format: `YYYY-MM-DD`.
                example: "2025-01-18"
              walletEventName:
                type: string
                description: The name of the wallet being debited.
                example: "Main account"
              walletAlias:
                type: string
                description: The alias of the wallet being debited.
                deprecated: true
              userFirstname:
                type: string
              userLastname:
                type: string
              userId:
                type: integer
                description: The unique identifier of the user.
              bankAccountId:
                deprecated: true
              beneficiaryId:
                type: integer
                description: The unique identifier of the payout Beneficiary.
              uniqueMandateReference:
                type: string
                description: |
                  The unique reference that unambiguiously identify a mandate signed between the user and the beneficiary. 
                
                  See the [Unique Mandate Reference (UMR)](/guide/overview/glossary.html#unique-mandate-reference-umr) article for more information.
              bankaccountIBAN:
                type: string
                example: "FR7616798000010001726649397"
              label:
                type: string
                maxLength: 140
                description: | 
                  The payout label that will be displayed on the receiver's bank account.
                  
                  Allowed characters: `a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 / - ? : ( ) . , ' + Space“.` 
                  * Accentuated characters will be replaced by the same characters without accent 
                  * `/n` character are removed
                  * Must not start or end with `/`
                  * Must not contain `//`
              amount:
                type: string
                description: | 
                  The amount of the payout.
                  * Must be greater than `0`. 
                  * Must be specified as a number with 2 decimals. 
                  
                  For example `180.99` for 180,99 euros and `120.00` for 120 euros.
                example: "120.67"
              currency:
                type: string
                format: ISO 4217
                description: |
                  The currency of the transfer amount. 
                  
                  Format: [ISO 4217](/guide/api-basics/data-format.html#currencies).
                example: "EUR"
              partnerFee:
                type: string
              createdDate:
                type: string
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                description: |
                  Format: `YYYY-MM-DD HH:mm:ss`
                example: "2024-04-23 12:34:12"
              modifiedDate:
                type: string
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                description: |
                  Format: `YYYY-MM-DD HH:mm:ss`
                example: "2024-04-23 12:34:12"
              virtualIbanId:
                type: integer
                description: The unique identifier of the Virtual IBAN.
                nullable: true
              virtualIbanReference:
                type: string
                maxLength: 255
                example: "TRZ-VIBAN-001"
                nullable: true
              codeStatus:
                type: string
                description: |
                  The status code of the payout. See [payout statuses](/guide/transfers/introduction.html#payout-statuses-codestatus) for more information.
                enum: ["160001", "160002", "160003", "160004", "160005", "160006", "160007", "160008", "160009", "160010", "160011", "160012", "160013", "160014", "160015"]
              informationStatus:
                type: string
                description: Additional information regarding the code status, if any.
              supportingFileLink:
                type: string
                description: |
                  The link of the support file, which may be mandatory in some situations. Learn more in the [SCT processing](/guide/transfers/credit-transfer.html#processing) article.
              endToEndId:
                type: string
                maxLength: 35
                description: Unique identification assigned by the final client to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain.
              reasonCode:
                type: string
                description: |
                  Reason code for SEPA R-transactions as defined by the European Payment Council. See [lists of reason codes](/guide/transfers/error-codes.html).
                nullable: true
              reasonDescription:
                type: string
                description: The description of the reason code.
                nullable: true
              internationalBeneficiaryId:
                type: string
                nullable: true
              quotationId:
                type: string
                nullable: true
              beneficiaryValidationId:
                type: string
                format: uuid
                description: The unique identifier of the beneficiary validation.
                example: "f8e4a7b2-c1d3-4e5a-8b0f-9c2d1e0a3b5c"
                nullable: true
              totalRows:
                type: integer
                description: |
                  The total numbers of objects matching your search, for pagination purposes. Only valued in the first object of the returned page, `null` otherwise.
              metadata:
                type: object
                nullable: true
    
    PayoutRefundObject:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the payout refund.
          example: "550e8400-e29b-41d4-a716-446655440000"
        payoutRefundTag:
          type: string
          nullable: true
          description: |
            Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
                    
            Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
          example: "fraud-recall-001"
        codeStatus:
          type: string
          description: Status code of the payout refund.
          enum: ["790001", "790002", "790003", "790004"]
        informationStatus:
          type: string
          enum: [CANCELED, PENDING, VALIDATED]
          description: Status of the payout refund.
        payoutId:
          type: string
          format: uuid
          description: The unique identifier of the original payout.
          example: "550e8400-e29b-41d4-a716-336655440000"
        requestAmount:
          type: number
          format: float
          nullable: true
          description: The amount of the refund, which can equal or inferior to the amount of the initial payout.
          example: 100.50
        requestCurrency:
          type: string
          enum: [EUR]
          nullable: true
          description: The currency of the refund.
          example: "EUR"
        requestComment:
          type: string
          nullable: true
          description: Comment for the refund request.
          example: "Fraudulent transaction detected"
        reasonCode:
          type: string
          enum: [DUPL, TECH, FRAD, CUST, AM09, AC03, MD01, MD06, MS02]
          description: Reason code for the refund.
          example: "DUPL"
        refundAmount:
          type: number
          format: float
          nullable: true
          description: The amount of the refund.
          example: 100.50
        refundCurrency:
          type: string
          enum: [EUR]
          nullable: true
          description: The currency of the refund.
          example: "EUR"
        refundDate:
          type: string
          format: date
          nullable: true
          description: Date on which the refund was processed.
          example: "2024-10-01"
        refundComment:
          type: string
          nullable: true
          description: Comment from the refund processing
          example: "Refund processed successfully"
        negativeResponseReasonCode:
          type: string
          nullable: true
          description: Reason code if the refund was rejected.
          example: "AM04"
        createdDate:
          type: string
          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
          description: |
            Format: `YYYY-MM-DD HH:mm:ss`
          example: "2024-04-23 12:34:12"
        modifiedDate:
          type: string
          # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
          description: |
            Format: `YYYY-MM-DD HH:MM:SS`
          example: "2024-04-23 12:34:12"

    PayoutRefundResponse:
      type: object
      required:
        - payoutRefunds
      properties:
        payoutRefunds:
          type: array
          items:
            $ref: '#/components/schemas/PayoutRefundObject'

    MassPayoutObject:
      type: object
      properties:
        massPayoutId:
          type: string
          format: uuid
          description: The unique identifier of the mass payout batch.
          example: "8b9dacf4-6acf-407b-953c-fcbb21355c1c"
        massPayoutTag:
          type: string
          description: |
            Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.

            Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
          example: "ref-pay-nov-2024"
        vopOptOut:
          type: boolean
          description: |
            Indicates that you have collected the end users' consent to opt out of the [Verification of Payee](/guide/overview/glossary.html#verification-of-payee-vop) service.
        createdDate:
          type: string
          description: |
            The date and time at which the mass payout batch was created. Format: `YYYY-MM-DD HH:mm:ss`
          example: "2024-04-24 08:55:26"
        processedDate:
          type: string
          description: |
            The date and time at which the mass payout batch processing ended. 
            
            Valued to `null` if processing is still in progress.

            Format: `YYYY-MM-DD HH:mm:ss`
          nullable: true
          example: "2024-04-24 09:55:26"
        createdPayouts:
          type: object
          nullable: true
          description: |
            The list of payouts that were successfully created.
          properties:
            count:
              type: integer
              description: The number of successfully created payouts.
              example: 20
            payoutIds:
              type: array
              items:
                type: string
                description: The unique identifier of the payout. uuid for SCT Inst.
                example: "12345"
        failedPayoutCreations:
          type: object
          nullable: true
          description: The list of payouts that weren't created.
          properties:
            count:
              type: integer
              description: Number of failed payout creations.
              example: 5
            payouts:
              type: array
              items:
                type: object
                properties:
                  tag:
                    type: string
                    description: The payoutTag for the failed creation.
                  reason:
                    type: string
                    description: The reason why the update failed for the given `id`.
                    enum:
                      - AUTHENTICATION_ERROR
                      - AUTHORIZATION_ERROR
                      - FUNCTIONAL_ERROR
                      - INPUT_VALIDATION_ERROR
                      - INVALID_PARAMETER_ERROR
                      - INVALID_USER_ID
                      - INVALID_WALLET_ID
                      - RESOURCE_NOT_FOUND_ERROR
                      - UNDEFINED_CURSOR_ERROR
                      - UNEXPECTED_ERROR
    PayoutRefund:
      type: object
      properties:
        payoutRefundTag:
          type: string
          nullable: true
        codeStatus:
          type: string
          nullable: true
        informationStatus:
          type: string
          nullable: true
        payoutTypeId:
          type: integer
          enum: [1,2,3,4]
        requestComment:
          type: string
          nullable: true
        reasonCode:
          type: string
          nullable: true
        refundDate:
          type: string
          nullable: true
        refundComment:
          type: string
          nullable: true
        payoutId:
          type: string
          nullable: true
        payoutTag:
          type: string
          maxLength: 250
          nullable: true
        beneficiaryId:
          type: string
          nullable: true
        beneficiaryName:
          type: string
          nullable: true
        label:
          type: string
          nullable: true
        endToEndId:
          type: string
          nullable: true
        uniqueMandateReference:
          type: string
          description: 
            The unique reference that unambiguiously identify a mandate signed between the user and the beneficiary. 
                          
            See the [Unique Mandate Reference (UMR)](/guide/overview/glossary.html#unique-mandate-reference-umr) article for more information.
          nullable: true
    Transfer:
      type: object
      properties:
        label:
          type: string
          nullable: true
        codeStatus:
          type: string
          description: |
            The code for the status of the transfer. See [Transfer statuses](/guide/transfers/introduction.html#transfer-statuses-codestatus) for more information.
          enum: ["150001", "150002", "150003", "150004", "150005", "150006"]
        tag:
          type: string
          nullable: true
        informationStatus:
          type: string
          nullable: true
          description: Additional information regarding the status of the transfer (if any).
        creditorWalletId:
          type: string
        creditorFirstName:
          type: string
        creditorLastName:
          type: string
        creditorLegalName:
          type: string
        creditorWalletEventName:
          type: string
        debtorWalletId:
          type: string
        debtorFirstName:
          type: string
        debtorLastName:
          type: string
        debtorLegalName:
          type: string
        debtorWalletEventName:
          type: string
    TransactionObject:
      type: object
      properties:
        transactions:
          type: array
          items:
            type: object
            properties:
              transactionId:
                type: integer
                description: The unique identifier of the Transaction object.
                example: 12345
              walletDebitId:
                type: integer
                description: The unique identifier of the debited Wallet.
                example: 12345
              walletCreditId:
                type: integer
                description: The unique identifier of the credited Wallet.
                example: 12345
              transactionType:
                type: string
                description: | 
                  The type the transaction. See the [Transactions](/guide/wallets/transactions.html#transaction-types-transactiontype) article for the list of possible values.
                enum:
                  - Payin
                  - Payout
                  - Transfer
                  - Payin Refund
                  - Card Transaction
                  - Payout Refund
                  - Payin Acquiring
                  - Payin Refund Acquiring
                  - SCTR Inst
                  - Payin SCT Instant Recall
                  - Payout SCT Instant Emit
                  - Payin SCT Instant Emit Recall
                  - Credit Transfer Returned
                  - Check Payin
                  - SDDE
                  - SDDR
                  - SDDR Reversal
                  - SCTR Recall
                  - Check Refund
                  - SCTR
                  - Credit International Transfer
              foreignId:
                type: string
                description: | 
                  The unique identifier of the initial operation that created the Transaction (e.g., `payinId`, `payoutId`, etc.)
                example: "266924b3-1f0c-48c0-b166-42c227a5a069"
              name:
                type: string
                description: The name of the transaction.
                example: "266924b3-1f0c-48c0-b166-42c227a5a069"
              description:
                type: string
                description: Additional information regarding the Transaction.
              valueDate:
                type: string
                description: |
                  The value date of the transaction (date applied for the payment).

                  Format: YYYY-MM-DD
                example: "2025-01-01"
              executionDate:
                type: string
                description: |
                  The date of the execution of the transaction.
                  
                  Format: `YYYY-MM-DD`
                example: "2025-01-01"
              amount:
                type: string
                format: float
                example: "25.55"
              walletDebitBalance:
                type: string
                format: float
                description: |
                  The balance of the debited Wallet after the transaction.
                example: "12.00"
              walletCreditBalance:
                type: string
                format: float
                description: |
                  The balance of the credited Wallet after the transaction.
                example: "12.00"
              currency:
                type: string
                format: ISO 4217
                description: |
                  The currency in the [ISO 4217](/guide/api-basics/data-format.html#currencies) format.
                example: "EUR"
              createdDate:
                type: string
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                description: |
                  The date and time at which the transaction was created.
                  
                  Format: `YYYY-MM-DD HH:mm:ss`
                example: "2025-01-02 13:00:12"
              totalRows:
                type: string
                description: |
                  The total numbers of objects matching your search, for pagination purposes. Only valued in the first object of the returned page, `empty` otherwise.
    WalletObject:
      type: object
      properties:
        wallets:
          type: array
          items:
            type: object
            properties:
              walletId:
                type: integer
                description: The unique identifier of the Wallet.
                example: 12345
              walletTypeId:
                type: integer
                description: |
                  The type of Wallet. Learn more in the [Wallet Types](/guide/wallets/introduction.html#types-of-wallets) documentation.
                enum: [9,10,15]
              walletStatus:
                type: string
                description: The status of the Wallet.
                enum:
                  - CANCELED
                  - PENDING
                  - VALIDATED
              codeStatus:
                type: integer
                description: |
                  See [Wallet status](/guide/wallets/introduction.html#wallet-status).
                enum:
                  - 120001
                  - 120002
                  - 120003
                  - 120004
                  - 120005
              informationStatus:
                type: string
                description: |
                  Additional information regarding the `codeStatus`, if any.
                nullable: true
              walletTag:
                type: string
                description: |
                  Custom attribute to use as you see fit. Learn more in the [Object tags](/guide/api-basics/objects-tags.html#objects-tags) article.
                    
                  Format: hc characters and `/` `!` `-` `_` `.` `*` `'` `(` `)`
                nullable: true
                example: "MAIN-WALLET-001"
              userId:
                type: integer
                description: The unique identifier of the User owning the Wallet.
                example: 12345
              userLastname:
                type: string
                description: The last name of the User owning the Wallet.
                example: "Oak"
              userFirstname:
                type: string
                description: The first name of the User owning the Wallet.
                example: "Alex"
              jointUserId:
                type: integer
                deprecated: true
                nullable: true
              tariffId:
                type: integer
                description: The fees applied to the Wallet, as defined by your contract with Treezor. Defaults to the value set by Treezor.
              eventName:
                type: string
                description: The name of the Wallet.
                example: "Main Wallet"
              eventAlias:
                type: string
                deprecated: true
                nullable: true
              eventDate:
                type: string
                deprecated: true
              eventMessage:
                type: string
                description: Can be used to describe the Wallet.
                example: "This is a description of the Main Wallet."
                nullable: true
              eventPayinStartDate:
                type: string
                deprecated: true
                nullable: true
              eventPayinEndDate:
                type: string
                deprecated: true
                nullable: true
              contractSigned:
                type: integer
                deprecated: true
                nullable: true
              bic:
                type: string
                description:  |
                  The [BIC](/guide/overview/glossary.html#bank-identifier-code-bic) of the Wallet, indicating in which country the wallet is domiciled. 
                    
                  This value may be required depending on your configuration. Learn more in the [Local IBAN](/guide/wallets/iban.html#local-iban) article.
                enum: ["TRZOFR21XXX","TRZODEB2XXX","TRZOITM2XXX","TRZOESM2XXX"]
                example: "TRZOFR21XXX"
              iban:
                type: string
                description: |
                  The [IBAN](/guide/wallets/iban.html) of the Wallet.
                example: "FR7630006000011234567890189"
              urlImage:
                type: string
                deprecated: true
                nullable: true
              currency:
                type: string
                description: The currency of the Wallet.
                example: "EUR"
              createdDate:
                type: string
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                description: |
                  The date and time at which the Wallet was created.

                  Format: `YYYY-MM-DD HH:mm:ss`
                example: "2023-11-08 10:21:10"
              modifiedDate:
                type: string
                # pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
                description: |
                  The date and time at which the Wallet was modified.

                  Format: `YYYY-MM-DD HH:mm:ss`
                example: "2024-11-08 10:21:10"
              payinCount:
                type: integer
                deprecated: true
                nullable: true
              payoutCount:
                type: integer
                deprecated: true
                nullable: true
              transferCount:
                type: integer
                deprecated: true
                nullable: true
              solde:
                type: number
                format: float
                description: |
                  The [current balance](/guide/wallets/balances.html) of the wallet.

                  Prefer the [balance](/guide/wallets/balances.html) endpoint for more accurate values.
                example: 816.45
              authorizedBalance:
                type: number
                format: float
                example: 816.45
              totalRows:
                type: integer
                nullable: true
                description: |
                  The total numbers of objects matching your search, for pagination purposes. Only valued in the first object of the returned page, `null` otherwise.
              country:
                type: string
                description: |
                  The country of the Wallet owner, inherited from the User object address.
                example: "FR"
    WalletDomiciliationTemplate:
      type: object
      properties:
        name:
          type: string
          example: "wallet.walletDomiciliation"
        description:
          type: string
          example: "Registration certificat"
        mimeType:
          type: string
          example: "text/html"
        variables:
          type: object
          properties:
            wallet:
              type: object
              properties:
                name:
                  type: string
                type:
                  type: string
                  example: "array"
                description:
                  type: string
                  example: "Wallet model"
                children:
                  type: array
                  items:
                    type: string
                parentName:
                  type: string
                  nullable: true
            user:
              type: object
              properties:
                name:
                  type: string
                  example: "user"
                type:
                  type: string
                  example: "array"
                description:
                  type: string
                  example: "User model"
                children:
                  type: array
                  items:
                    type: string
    WalletConfirmationLetterTemplate:
      type: object
      properties:
        name:
          type: string
          example: "wallet.confirmationLetter"
        description:
          type: string
          example: "Confirmation letter"
        mimeType:
          type: string
          example: "text/html"
        variables:
          type: object
          properties:
            wallet:
              type: object
            user:
              type: object
            balance:
              type: object
              properties:
                name:
                  type: string
                  example: "balance"
                type:
                  type: string
                  example: "array"
                description:
                  type: string
                  example: "balance model"
                children:
                  type: object
                  properties:
                    balance:
                      type: object
                    calculationDate:
                      type: object
                parentName:
                  type: string
                  nullable: true
            agentType:
              type: object
              properties:
                name:
                  type: string
                  example: "agentType"
                type:
                  type: string
                  example: "kv"
                description:
                  type: string
                  example: "agentType"
                children:
                  type: array
                  items: {}
                parentName:
                  type: string
                  nullable: true
            usersLR:
              type: object
              properties:
                name:
                  type: string
                  example: "usersLR"
                type:
                  type: string
                  example: "array"
                description:
                  type: string
                  example: "Users"
                children:
                  type: array
                  items: {}
                parentName:
                  type: string
                  nullable: true
    WalletClosureTemplate:
      type: object
      properties:
        name:
          type: string
          example: "wallet.walletClosure"
        description:
          type: string
          example: "Closure certificat"
        mimeType:
          type: string
          example: "text/html"
        variables:
          type: object
          properties:
            wallet:
              type: object
              properties:
                name:
                  type: string
                type:
                  type: string
                  example: "array"
                description:
                  type: string
                  example: "Wallet model"
                children:
                  type: array
                  items:
                    type: string
                parentName:
                  type: string
                  nullable: true
            user:
              type: object
              properties:
                name:
                  type: string
                  example: "user"
                type:
                  type: string
                  example: "array"
                description:
                  type: string
                  example: "User model"
                children:
                  type: array
                  items: 
                    type: string
    WalletBalanceTemplate:
      type: object
      properties:
        name:
          type: string
          example: "wallet.walletBalance"
        description:
          type: string
          example: "Balance certificat"
        mimeType:
          type: string
          example: "text/html"
        variables:
          type: object
          properties:
            wallet:
              type: object
              properties:
                name:
                  type: string
                type:
                  type: string
                  example: "array"
                description:
                  type: string
                  example: "Wallet model"
                children:
                  type: array
                  items: 
                    type: string
                parentName:
                  type: string
                  nullable: true
            user:
              type: object
              properties:
                name:
                  type: string
                  example: "user"
                type:
                  type: string
                  example: "array"
                description:
                  type: string
                  example: "User model"
                children:
                  type: array
                  items: 
                    type: string
            balance:
              type: object
              properties:
                name:
                  type: string
                  example: "balance"
                type:
                  type: string
                  example: "array"
                description:
                  type: string
                  example: "Balance model"
                children:
                  type: array
                  items:
                    type: string
    WalletStatementTemplate:
      type: object
      properties:
        name:
          type: string
          example: "wallet.statement"
        description:
          type: string
          example: "Statement"
        mimeType:
          type: string
          example: "text/html"
        variables:
          type: object
          properties:
            wallet:
              type: object
              properties:
                name:
                  type: string
                type:
                  type: string
                  example: "array"
                description:
                  type: string
                  example: "Wallet model"
                children: 
                  type: object
                  properties:
                    iban:
                      type: object
                      properties:
                        name:
                          type: string
                          example: "iban"
                        type:
                          type: string
                          example: "kv"
                        description:
                          type: string
                          example: "Wallet iban"
                        children:
                          type: array
                          items: {}
                        parentName:
                          type: string
                          example: "wallet"
                    bic:
                      type: object
                      properties:
                        name:
                          type: string
                          example: "iban"
                        type:
                          type: string
                          example: "kv"
                        description:
                          type: string
                          example: "Wallet iban"
                        children:
                          type: array
                          items: {}
                        parentName:
                          type: string
                          example: "wallet"
                parentName:
                  type: string
                  nullable: true
            user:
              type: object
              properties:
                name: 
                  type: string
                  example: "user"
                type:
                  type: string
                  example: "array"
                description:
                  type: string
                  example: "User model"
                children:
                  type: object
                  properties:
                    title:
                      type: object
                    firstname:
                      type: object
                    lastname:
                      type: object
                    address1:
                      type: object
                    address2:
                      type: object
                    address3:
                      type: object
                    postcode:
                      type: object
                    city:
                      type: object
                    country:
                      type: object
                    userTypeId:
                      type: object
                    state:
                      type: object
            totalDebit:
              type: object
            totalCredit:
              type: object
            totalAmountFees:
              type: object
            totalAmountCreditNote:
              type: object
            operations:
              type: object
            firstBalance:
              type: object
            lastBalance:
              type: object

    WalletAddressDetailsTemplate:
      type: object
      properties:
        name:
          type: string
          example: "wallet.address_details"
        description:
          type: string
          example: "Account Details"
        mimeType:
          type: string
          example: "text/html"
        variables:
          type: object
          properties:
            wallet:
              type: object
            user:
              type: object
            treezorAddress:
              type: object
            
    PayoutProofOfPayoutTemplate:
      type: object
      properties:
        name:
          type: string
          example: "payout.proof_of_payout"
        description:
          type: string
          example: "Proof of Payout"
        mimeType:
          type: string
          example: "text/html"
        variables:
          type: object
          properties:
            wallet:
              type: object
            user:
              type: object
            payout:
              type: object
            beneficiarie:
              type: object

    EmailUserOnboardingConfirmationHtmlTemplate:
      type: object
      properties:
        name:
          type: string
          example: "email.user.onboarding_confirmation_html"
        description:
          type: string
          nullable: true
        mimeType:
          type: string
          example: "text/html"
        variables:
          type: object
          properties:
            confirmation_link:
              type: object
              properties:
                name:
                  type: string
                  example: "confirmation_link"
                type:
                  type: string
                  example: "kv"
                description:
                  type: string
                  example: "A link used to validate a newly created user account"
                children:
                  type: array
                  items: {}
                parentName:
                  type: string

    EmailUserOnboardingConfirmationTextTemplate:
      type: object
      properties:
        name:
          type: string
          example: "email.user.onboarding_confirmation_text"
        description:
          type: string
          nullable: true
        mimeType:
          type: string
          example: "text/plain"
        variables:
          type: object
          properties:
            confirmation_link:
              type: object
              properties:
                name:
                  type: string
                  example: "confirmation_link"
                type:
                  type: string
                  example: "kv"
                description:
                  type: string
                  example: "A link used to validate a newly created user account"
                children:
                  type: array
                  items: {}
                parentName:
                  type: string

    EmailUserPasswordForgotHtmlTemplate:
      type: object
      properties:
        name:
          type: string
          example: "email.user.password_forgot_html"
        description:
          type: string
          nullable: true
        mimeType:
          type: string
          example: "text/html"
        variables:
          type: object
          properties:
            token:
              type: object
              properties:
                name:
                  type: string
                  example: "token"
                type:
                  type: string
                  example: "kv"
                description:
                  type: string
                  example: "The forgot password token"
                children:
                  type: array
                  items: {}
                parentName:
                  type: string
                  nullable: true
            confirmation_link:
              type: object
              properties:
                name:
                  type: string
                  example: "confirmation_link"
                type:
                  type: string
                  example: "kv"
                description:
                  type: string
                  example: "The link to change password"
                children:
                  type: array
                  items: {}
                parentName:
                  type: string
                  nullable: true
            firstname:
              type: object
              properties:
                name:
                  type: string
                  example: "firstname"
                type:
                  type: string
                  example: "kv"
                description:
                  type: string
                  example: "End user firstname"
                children:
                  type: array
                  items: {}
                parentName:
                  type: string
                  nullable: true
            lastname:
              type: object
              properties:
                name:
                  type: string
                  example: "lastname"
                type:
                  type: string
                  example: "kv"
                description:
                  type: string
                  example: "End user lastname"
                children:
                  type: array
                  items: {}
                parentName:
                  type: string
                  nullable: true
            email:
              type: object
              properties:
                name:
                  type: string
                  example: "email"
                type:
                  type: string
                  example: "kv"
                description:
                  type: string
                  example: "End user email"
                children:
                  type: array
                  items: {}
                parentName:
                  type: string
                  nullable: true
            expiration_date:
              type: object
              properties:
                name:
                  type: string
                  example: "expiration_date"
                type:
                  type: string
                  example: "kv"
                description:
                  type: string
                  example: "The link expiration date"
                children:
                  type: array
                  items: {}
                parentName:
                  type: string
                  nullable: true

    EmailUserPasswordForgotTextTemplate:
      type: object
      properties:
        name:
          type: string
          example: "email.user.password_forgot_text"
        description:
          type: string
          nullable: true
        mimeType:
          type: string
          example: "text/plain"
        variables:
          type: object
          properties:
            token:
              type: object
              properties:
                name:
                  type: string
                  example: "token"
                type:
                  type: string
                  example: "kv"
                description:
                  type: string
                  example: "The forgot password token"
                children:
                  type: array
                  items: {}
                parentName:
                  type: string
                  nullable: true
            confirmation_link:
              type: object
              properties:
                name:
                  type: string
                  example: "confirmation_link"
                type:
                  type: string
                  example: "kv"
                description:
                  type: string
                  example: "The link to change password"
                children:
                  type: array
                  items: {}
                parentName:
                  type: string
                  nullable: true
            firstname:
              type: object
              properties:
                name:
                  type: string
                  example: "firstname"
                type:
                  type: string
                  example: "kv"
                description:
                  type: string
                  example: "End user firstname"
                children:
                  type: array
                  items: {}
                parentName:
                  type: string
                  nullable: true
            lastname:
              type: object
              properties:
                name:
                  type: string
                  example: "lastname"
                type:
                  type: string
                  example: "kv"
                description:
                  type: string
                  example: "End user lastname"
                children:
                  type: array
                  items: {}
                parentName:
                  type: string
                  nullable: true
            email:
              type: object
              properties:
                name:
                  type: string
                  example: "email"
                type:
                  type: string
                  example: "kv"
                description:
                  type: string
                  example: "End user email"
                children:
                  type: array
                  items: {}
                parentName:
                  type: string
                  nullable: true
            expiration_date:
              type: object
              properties:
                name:
                  type: string
                  example: "expiration_date"
                type:
                  type: string
                  example: "kv"
                description:
                  type: string
                  example: "The link expiration date"
                children:
                  type: array
                  items: {}
                parentName:
                  type: string
                  nullable: true
    UserInfo:
      type: object
      properties:
        userTypeId:
          type: integer
          description: The type of the user.
          enum: [1, 2, 3, 4]
        title:
          type: string
          example: "MX"
          enum:
            - M
            - MME
            - MLLE
            - MX
        firstname:
          type: string
          description: The first name of the User.
          example: "Alex"
        lastname:
          type: string
          description: The last name of the User.
          example: "Oak"
        birthday:
          type: string
          format: date
          description: |
            The birth date of the User.
          example: "1989-09-03"
        placeOfBirth:
          type: string
          maxLength: 150
          description: The city in which the User was born.
          example: "Paris"
        birthCountry:
          type: string
          description: The country in which the User was born.
          example: "France"
        legalName:
          type: string
          description: The name of the legal entity. 
          example: "Tree Company"
        legalRegistrationNumber:
          type: string
          description: The registration number of the legal entity.
          example: "34567"
        legalRegistrationDate:
          type: string
          format: date
          example: "2021-09-23"

    WalletInfo:
      type: object
      properties:
        walletStatus:
          type: string
          description: The status of the wallet.
          enum:
            - CANCELED
            - PENDING
            - VALIDATED
        bic:
          type: string
          description: |
            The [BIC](/guide/overview/glossary.html#bank-identifier-code-bic) of the Wallet, indicating in which country the wallet is domiciled. 
          example: "TRZOFR21XXX"
        iban:
          type: string
          description: |
            The [IBAN](/guide/wallets/iban.html) of the Wallet.
          example: "FR7616798000010000101039007"
        createdDate:
          type: string
          description: The date and time at which the Wallet was created.
          example: "2021-09-23 16:33:50"

    WalletClosureInfo:
      type: object
      properties:
        walletStatus:
          type: string
          description: The status of the wallet.
          enum:
            - CANCELED
            - PENDING
            - VALIDATED
        bic:
          type: string
          description: |
            The [BIC](/guide/overview/glossary.html#bank-identifier-code-bic) of the account.
          example: "TRZOFR21XXX"
        iban:
          type: string
          description: |
            The [IBAN](/guide/wallets/iban.html#virtual-iban) of the account.
          example: "FR7630006000011234567890189"
        modifiedDate:
          type: string
          description: The date and time at which the Wallet was last updated.
          example: "2021-09-23 16:33:50"

    BalanceInfo:
      type: object
      properties:
        currentBalance:
          type: number
          format: float
          description: |
            The amount of money currently available on the wallet without considering pending operations. 

            See [Balance](/guide/wallets/balances.html) article for more information.
          example: 638.98
        calculationDate:
          type: string
          description: The date and time at which the balance was calculated.
          example: "2021-09-23 16:33:50"

    BalanceRawResponse:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/UserInfo'
        wallet:
          $ref: '#/components/schemas/WalletInfo'
        balance:
          $ref: '#/components/schemas/BalanceInfo'
        certificateDate:
          type: string
          format: date-time
          description: The date and time at which the certificate was generated.
          example: "2025-06-02T13:07:58+00:00"

    ClosureRawResponse:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/UserInfo'
        wallet:
          $ref: '#/components/schemas/WalletClosureInfo'
        modifiedDate:
          type: string
          description: The date and time at which the account was closed.
          format: date-time
          example: "2025-06-02T13:07:58+00:00"
        certificateDate:
          type: string
          format: date-time
          description: The date and time at which the certificate was generated.
          example: "2025-06-02T13:07:58+00:00"

    RegistrationRawResponse:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/UserInfo'
        wallet:
          $ref: '#/components/schemas/WalletInfo'
        certificateDate:
          type: string
          format: date-time
          description: The date and time at which the certificate was generated.
          example: "2025-06-02T13:07:58+00:00"

    ComputedCertificateResponse:
      type: object
      properties:
        link:
          type: string
          format: uri
          description: The URL to download the PDF file.
          example: https://xxx.s3.eu-west-3.amazonaws.com/tmp/xxx.pdf
        expireIn:
          type: integer
          description: The time after which the download link expires (in seconds).
          default: 300

    Camt053Document:
      type: object
      xml:
        name: Document
        namespace: 'urn:iso:std:iso:20022:tech:xsd:camt.053.001.12'
      properties:
        BkToCstmrStmt:
          type: object
          properties:
            GrpHdr:
              type: object
              properties:
                MsgId:
                  type: string
                CreDtTm:
                  type: string
                  format: date-time
            Stmt:
              type: object
              properties:
                Id:
                  type: string
                CreDtTm:
                  type: string
                  format: date-time
                FrToDt:
                  type: object
                  properties:
                    FrDtTm:
                      type: string
                      format: date-time
                    ToDtTm:
                      type: string
                      format: date-time
                Acct:
                  type: object
                  properties:
                    Id:
                      type: object
                      properties:
                        IBAN:
                          type: string
                    Ccy:
                      type: string
                Bal:
                  type: array
                  items:
                    type: object
                    properties:
                      Tp:
                        type: object
                        properties:
                          CdOrPrtry:
                            type: object
                            properties:
                              Cd:
                                type: string
                                description: Balance type code
                                enum: [OPBD, CLBD, CLAV]
                      Amt:
                        type: string
                        description: Amount with Ccy attribute
                      CdtDbtInd:
                        type: string
                        enum: [CRDT, DBIT]
                      Dt:
                        type: object
                        properties:
                          DtTm:
                            type: string
                            format: date-time
                Ntry:
                  type: array
                  items:
                    type: object
                    properties:
                      NtryRef:
                        type: string
                        description: Transaction ID
                      Amt:
                        type: string
                        description: Amount with Ccy attribute
                      CdtDbtInd:
                        type: string
                        enum: [CRDT, DBIT]
                      Sts:
                        type: object
                        properties:
                          Cd:
                            type: string
                            enum: [BOOK]
                      ValDt:
                        type: object
                        properties:
                          Dt:
                            type: string
                            format: date
                      BkTxCd:
                        type: object
                        properties:
                          Domn:
                            type: object
                            properties:
                              Cd:
                                type: string
                              Fmly:
                                type: object
                                properties:
                                  Cd:
                                    type: string
                                  SubFmlyCd:
                                    type: string
                      NtryDtls:
                        type: object
                        properties:
                          TxDtls:
                            type: object
                            properties:
                              RltdPties:
                                type: object
                                properties:
                                  Dbtr:
                                    $ref: '#/components/schemas/Camt053Party'
                                  DbtrAcct:
                                    $ref: '#/components/schemas/Camt053Account'
                                  Cdtr:
                                    $ref: '#/components/schemas/Camt053Party'
                                  CdtrAcct:
                                    $ref: '#/components/schemas/Camt053Account'
                              RltdAgts:
                                type: object
                                properties:
                                  DbtrAgt:
                                    $ref: '#/components/schemas/Camt053Agent'
                                  CdtrAgt:
                                    $ref: '#/components/schemas/Camt053Agent'
                              AddtlTxInf:
                                type: string
                                description: Transaction description
    Camt053Party:
      type: object
      properties:
        Pty:
          type: object
          properties:
            Nm:
              type: string
            PstlAdr:
              type: object
              properties:
                AdrLine:
                  type: array
                  items:
                    type: string
    Camt053Account:
      type: object
      properties:
        Id:
          type: object
          properties:
            IBAN:
              type: string
    Camt053Agent:
      type: object
      properties:
        FinInstnId:
          type: object
          properties:
            BICFI:
              type: string

tags:
  - name: Account Documents
    description: |
      Treezor allows you to generate various official documents related to your [Wallet](/guide/wallets/introduction.html). 
      
      These include **account details** (IBAN and owner identity), **account statements** that summarize monthly operations affecting the [balance](/guide/wallets/balances.html), and **certificates** for account closure, domiciliation, or balance, that may be required for reporting or administrative purposes.

      _Related articles: [Account documents](/guide/wallets/account-documents.html) | [Wallets](/guide/wallets/introduction.html)_
  - name: Acquiring (Card Topups)
    description: | 
      Card Acquiring consists of capturing funds from a third-party card to credit a Treezor [Wallet](/guide/wallets/introduction.html). 

      _Related articles: [Card Acquiring](/guide/acquiring/introduction.html)_
  - name: Acquiring (Simulation)
    description: | 
      Dedicated set of endpoints so emulate card acquiring payins, and the related notifications.

      _Related articles: [Card Acquiring](/guide/acquiring/introduction.html) | [Emulation](/guide/acquiring/faking-operations.html)_
  - name: API Templates
    description: |
      Treezor offers a series of templates to customize emails and files, that you can manage via dedicated endpoints. Please bear in mind templates are base64-encoded files.

      _Related articles: [Templates](/guide/api-basics/templates.html) | [Email Templates](/guide/api-basics/emails.html#templates)_
  - name: Authentication
    description: |
      Treezor leverages the [OAuth2 framework](https://en.wikipedia.org/wiki/OAuth) and [JSON Web Token (JWT)](/guide/overview/glossary.html#json-web-token-jwt) which allows for a wide range of authentication flows.
      
      The obtained Bearer access token can then be used in the Authorization headers to authenticate your calls to the Treezor API.

      _Related articles: [Authentication](/guide/api-basics/authentication.html)_
  - name: Balances
    description: |
      The Balance object provides the amount available on a given Wallet. Read more about the different kind of balances in the [Balance definition](/guide/wallets/balances.html) of the Glossary.

      _Related articles: [Balances](/guide/wallets/balances.html) | [Wallets](/guide/wallets/introduction.html)_
  - name: Beneficiaries
    description: |
      The Beneficiary object represents a bank account that is outside of your Treezor ecosystem (as opposed to [Wallets](/guide/dashboard/wallets.html#wallets)). 
      
      They are therefore the target of payouts (SEPA Direct Debit and SEPA Credit Transfers), and are necessarily attached to a User.

      _Related articles: [Beneficiaries](/guide/transfers/beneficiaries.html) | [SEPA Transfers](/guide/transfers/introduction.html)_
  - name: Businesses
    description: |
      Treezor provides dedicated endpoints to help you check information regarding a legal entity, provided you have its VAT or registration number.

      _Related articles: [Checking for veracity](/guide/users/legal-entity.html#checking-for-veracity) | [Legal Entities](/guide/users/legal-entity.html)_
  - name: Cards
    description: |
      The Card object represents a Physical or Virtual Card issued with Treezor services.

      Following your [Card Program](/guide/cards/introduction.html#card-program) and your agreement with Treezor, you can issue, manage, and configure cards with options, restrictions, and limits to best suit your use case.

      _Related articles: [Cards](/guide/cards/introduction.html) | [Creation](/guide/cards/creation.html) | [Modifications](/guide/cards/modification.html) | [Restrictions & limits](/guide/cards/restrictions-limits.html)_
  - name: Cards Bulk Creation
    description: |
      Treezor allows you to create cards in bulk with a dedicated set of endpoints.

      _Related articles: [Bulk Creation](/guide/cards/creation.html#bulk-creation) | [Cards](/guide/cards/introduction.html)_
  - name: Card User Bulk Creation
    description: |
      Treezor allows you to create users and cards in bulk from a CSV file. This feature is designed for use cases like instant issuing where you need to create multiple users with their associated cards from a list.

      The process follows three steps: validate the CSV file (optional), create the bulk order, and monitor the order progress. A detailed execution report is available once processing is complete.

      _Related articles: [Creating Users and Cards from CSV](/guide/cards/creation.html#creating-users-and-cards-from-csv) | [Cards](/guide/cards/introduction.html)_
  - name: Card Bulk Updates
    description: |
      Treezor allows you to update cards in bulk with a dedicated set of endpoints.

      _Related articles: [Bulk Updates](/guide/cards/restrictions-limits.html#update-limits-in-bulk) | [Cards](/guide/cards/introduction.html)_      
  - name: Cards Digitalization
    description: |
      **Deprecated** – See [Digitized Cards](/api-reference/api-endpoints.html#tag/Digitized%20Cards/tavRequestPOST) instead.
  - name: Card 3DSecure Enrollment (SCA)
    description: |
      When eligible to SCA, most card transactions must be authenticated, hence ensuring the legitimate cardholder is initiating the transaction. 

      For the authentication step to be SCA-compliant, you must enroll the card for out of band authentication.

      _Related articles: [Card enrollment](/guide/strong-customer-authentication/securing-endpoints.html#sca-for-card-transactions) | [SCA](/guide/strong-customer-authentication/introduction.html)_
  - name: Card Rulesets (MDC)
    description: |
      The Ruleset object of the Multi-Criteria Dynamic Card rules engine allows you to authorize or refuse a Card Transaction based on your own set of rules.

      _Related articles: [Multi-Criteria Dynamic Card](/guide/cards/transactions-rules-engine.html)_
  - name: Card Transactions 
    description: |
      The Card Transaction object represents a step of a card payment made with a Treezor-issued Card (e.g., authorization, settlement, or refund).

      Card Transactions relating to the same payment (or payment attempt) have the same `paymentId` value.

      _Related articles: [Card Transactions](/guide/cards/transactions.html) | [Transactions life cycle](/guide/cards/transactions-lifecycle.html) | [Transaction examples](/guide/cards/transactions-examples.html)_
  - name: Card Transactions Authentication (SCA)
    description: |
      When eligible to SCA, most online card transactions must be authenticated, to ensure the legitimate cardholder is initiating the transaction.

      Treezor offers a series of endpoint to handle the authentication of a user, and simulate authentication requests to the server to facilitate your implementation.

      _Related articles: [SCA for Card Transactions](/guide/strong-customer-authentication/securing-endpoints.html#sca-for-card-transactions) | [Transactions authentication (SCA)](/guide/cards/transactions-authentication.html) | [Card Transactions](/guide/cards/transactions.html)_
  - name: Country Restriction Groups
    description: |
      The Country Restriction Group object is a whitelist or blacklist of countries. These lists allow you to specify if a given card should be used in specific countries (or forbidden in some countries).

      _Related articles: [List-based restrictions](/guide/cards/restrictions-limits.html#country-restrictions) | [Cards](/guide/cards/introduction.html)_
  - name: Digitized Cards
    description: |
      The digitization of a Card is the act of tokenizing an existing Card and store it in a Google Pay, Apple Pay, or Samsung Pay wallet.

      _Related articles: [X-Pay](/guide/cards/x-pay-google-apple.html) | [Cards](/guide/cards/introduction.html)_
  - name: Mandates
    description: |
      The Mandate object represents the formal document allowing a [Legal Entity](/guide/users/legal-entity.html) to initiate a transfer of funds from somebody else's account, to theirs. 

      The transfer is made using [SEPA Direct Debit (SDDE)](direct-debit#emitted-direct-debits-sdde) and can be used to receive one-time or recurring payments.

      _Related articles: [Mandates](/guide/transfers/mandates.html) | [SEPA Direct Debit](/guide/transfers/direct-debit.html#emitted-direct-debits-sdde)_
  # - name: Mass Payouts
  #   description: |
  #     Related articles: [Mass Payout](/guide/transfers/credit-transfer.html#mass-scte-mass-payout) | [SEPA Transfers](/guide/transfers/introduction.html)
  - name: MCC Lists (MDC)
    description: | 
      The MCC List of the Multi-Criteria Dynamic Card rules engine allows you to predefine and manage lists of [Merchant Category Codes (MDCC)](/guide/overview/glossary.html#merchant-category-code-mcc) that you can then add to your Rulesets.

      _Related articles: [Multi-Criteria Dynamic Card](/guide/cards/transactions-rules-engine.html)_
  - name: MCC Restriction Groups
    description: |
      The MMC Restriction Group object represents a list-based restriction allowing you to limit the usage of the card to specific categories of merchants.

      _Related articles: [List-based restrictions](/guide/cards/restrictions-limits.html#mcc-restrictions) | [Cards](/guide/cards/introduction.html)_
  - name: Merchant ID Restriction Groups
    description: |
      The MID Restriction Group object is a list-based restriction allowing you to limit the usage of the card to specific merchants.

      _Related articles: [List-based restrictions](/guide/cards/modification.html#list-based-restrictions) | [Cards](/guide/cards/introduction.html)_
  - name: Merchant ID Metadata
    description: |
      In some cases, the [Merchant Id (MID)](/guide/overview/glossary.html#merchant-identification-number-mid) may not be up-to-date or the given information not enough for you to act on it. 
      
      Treezor offers endpoints to add metadata to MIDs, hence allowing you to add human-readable information as you see fit.

      _Related articles: [MID Metadata](/guide/cards/restrictions-limits.html#mid-metadata) | [Cards](/guide/cards/introduction.html)_
  - name: MID Lists (MDC)
    description: |
      The MID List of the Multi-Criteria Dynamic Card rules engine allows you to predefine and manage lists of [Merchant IDs (MID)](/guide/overview/glossary.html#merchant-identification-number-mid) that you can then add to your Rulesets.

      _Related articles: [Multi-Criteria Dynamic Card](/guide/cards/transactions-rules-engine.html)_
  - name: Operations
    description: |
      The Operation object represents for banking operations originating from or targeting a [Wallet](/guide/wallets/introduction.html) (i.e., Card Transactions, Payins, Payouts, and Transfers) and their refunds. 
      
      Each Operation summarizes the initial transaction with read-only information such as the nature, status, amount, origin, and destination.

      _Related articles: [Operations](/guide/wallets/operations.html)_
  - name: Payins
    description: |
      The Payin object represents a movement of fund from an external account to a Treezor Wallet, and thus regardless of the means of payment used (SEPA Transfers, Checks, Card Top-ups).

      _Related articles: [SCTR](/guide/transfers/credit-transfer.html#received-credit-transfers-sctr) | [SDDE](/guide/transfers/direct-debit.html#emitted-direct-debits-sdde) | [Card top-up](/guide/acquiring/introduction.html) | [Check](/guide/cheques/introduction.html)_
  - name: Payin Refunds
    description: |
      The Payin Refund object represents the reimbursement of a Payin.

      Related articles: [SCTR Recalls](/guide/transfers/sepa-recalls.html#receiving-sctr-recalls)
  - name: Payouts
    description: |
      The Payout object represents a movement of funds from a Treezor Wallet to an external account, specifically the ones made through SEPA Transfers.

      _Related articles: [SCTE](/guide/transfers/credit-transfer.html#emitted-credit-transfers-scte) | [SDDR](/guide/transfers/direct-debit.html#received-direct-debits-sddr) | [Transfers](/guide/transfers/introduction.html)_
  - name: Payout Refunds
    description: |
      The Payout Refund object represents the reimbursement of a Payout. 

      _Related articles: [SCTE Inst Recalls](/guide/transfers/sepa-recalls.html#emitting-scte-inst-recalls) | [Refunding an SDDR](/guide/transfers/direct-debit.html#refunding-an-sddr)_
  - name: Recalls
    description: |
      Recalls occur when the originator of a [SEPA Credit Transfer (SCT)](/guide/overview/glossary.html#sepa-credit-transfer-sct) ask to reverse the transfer.

      Treezor offers endpoints to generate these requests or answers them depending on the type of the initial transfer.

      _Related articles: [Recalls & RROs](/guide/transfers/sepa-recalls.html)_
  - name: Scheduled Payments
    description: |
      Scheduled Payment orders allow you to plan a payment execution in the future, whether it is a unique operation or recurring ones. 
      
      Scheduled Payments can be used for both [Payouts (SCTE)](/guide/transfers/credit-transfer.html#emitted-credit-transfers-scte) and [Wallet-to-Wallet Transfers](/guide/wallets/wallet-to-wallet.html#wallet-to-wallet-transfers).
      
      _Related articles: [Scheduled Payments](/guide/transfers/scheduled-payments.html) | [SCTE](/guide/transfers/credit-transfer.html#emitted-credit-transfers-scte) | [Wallet-to-Wallet](/guide/transfers/wallet-to-wallet.html)_
  - name: SCA
    description: |
      The SCA Wallet object represents the secure enclave locally present on a device, which contains the private key for Strong Customer Authentication.

      _Related articles: [SCA Wallets](/guide/strong-customer-authentication/introduction.html#sca-wallet-object) | [SCA](/guide/strong-customer-authentication/introduction.html)_
  - name: SCA External Operations
    description: |
      The External Operation object represents any end user sensitive action that you need to declare when eligible to Strong Customer Authentication.

      When applying SCA outside of Treezor services, you're legally required to declare these actions to Treezor. Treezor then uses these declarations for reporting to the regulator.

      _Related articles: [SCA External Operations](/guide/strong-customer-authentication/securing-endpoints.html#declaring-sca-external-operations) | [SCA](/guide/strong-customer-authentication/introduction.html)_
  - name: SCA Proof Simulation
    description: |
      You can generate fake SCA proofs in Sandbox for testing your strong customer authentication integration. 

      _Related articles: [SCA Proof Simulation](/guide/strong-customer-authentication/faking-operations.html#simulate-sca-proof) | [SCA](/guide/strong-customer-authentication/introduction.html)_
  - name: Transactions
    description: |
      Transactions are a read-only representation of a settled banking operations on a [Wallet](./introduction).

      Please note detailed [Operations](/guide/wallets/operations.html) are more adequate to show real-time cashflow, with pending fund movements.

      _Related articles: [Transactions](/guide/wallets/transactions.html) | [Wallets](/guide/wallets/introduction.html)_
  - name: Transfers
    description: |
      The Transfer object represents a movement of funds from one Treezor Wallet to another.

      Both Wallets must belong to the same Treezor environment in order to perform a Wallet-to-Wallet Transfer (also referred to as peer-to-peer or P2P).

      _Related articles: [Wallet-to-Wallet](/guide/transfers/wallet-to-wallet.html) | [Wallets](/guide/wallets/introduction.html)_
  - name: User Document Pre-review
    description: |
      Dedicated set of endpoints for uploading documents to Treezor with a built-in pre-validation process.

      * Users upload files through pre-signed forms. 
      * These files are stored on dedicated servers while your teams review them. 
      * The actual Document objects are created in the Treezor API once the files are validated.

      _Related articles: [Document Pre-review](/guide/user-verification/documents-prereview.html) | [User verification](/guide/user-verification/introduction.html)_
  - name: User Documents
    description: |
      Documents are evidence required by Treezor to ensure Users are who they claim to be.

      During the KYC/B review, Treezor compares documents to the user’s declarative data. 
      The user is verified if the documents are in order (as well as any other verification requirement).
      
      _Related articles: [Documents](/guide/user-verification/documents.html) | [User verification](/guide/user-verification/introduction.html)_
  - name: User KYC Review
    description: |
      Treezor is legally obligated to verify the identity of the users using its services, whether it's you as a company or your end users.

      Once you've provided all the relevant information regarding a user, you may request the KYC Review, so that Treezor's team can either validate or refuse the user.

      _Related articles: [KYC Request](/guide/user-verification/kyc-request.html) | [User verification](/guide/user-verification/introduction.html)_
  - name: User Relationships
    description: |
      The User Relationship object allows you to link entities together (e.g., legal entity with an individual, or two individuals) via a granular and dynamic role mapping.

      _Related articles: [Relationships](/guide/users/relationships.html) | [Users](/guide/users/introduction.html)_
  - name: User Tax Residences
    description: |
      All users (both physical users and legal entities) going through the KYC verification process must declare at least one country of tax residency. 
      
      This is an obligation enforced by the [CRS](/guide/overview/glossary.html#common-reporting-standard-crs) and [FATCA](/guide/overview/glossary.html#foreign-account-tax-compliance-act-fatca).

      _Related articles: [Tax residence](/guide/users/tax-residence.html) | [User verification](/guide/user-verification/introduction.html)_
  - name: Users
    description: |
      The User object usually represents your customers, also referred to as end users. They can either be physical users or legal entities.

      _Related articles: [Physical Users](/guide/users/physical.html) | [Legal Entities](/guide/users/legal-entity.html) | [Users](/guide/users/introduction.html)_
  - name: Verification Solutions (KYC)
    description: |
      Treezor relies on several verification solutions to ease the physical user verification process. 
      
      The solutions available to you depend on the type of user and the distribution country.

      _Related articles: [User verification](/guide/user-verification/introduction.html)_
  - name: Virtual IBANs
    description: |
      In addition to the automatically assigned IBAN, Virtual IBANs can be created. Wallets can have as many Virtual IBANs as you see fit, to answer a large variety of use cases.

      _Related articles: [IBAN](/guide/wallets/iban.html) | [Wallets](/guide/wallets/introduction.html)_
  - name: Wallets
    description: |
      The Wallet object is like an account holding funds. They are necessary for any type of transaction in the Treezor environment.

      Wallets are usually  attached to your end users, allowing for the setup of their means of payment (cards, transfers, etc.). 
      Treezor offers various types of wallets to adapt to multiple use cases and technical architectures while remaining compliant in a highly regulated context.

      _Related articles: [Wallets](/guide/wallets/introduction.html)_