Toqio Card Lifecycle API

openapi: 3.0.0
info:
  description: Endpoints to manage client accounts
  version: v1.0.0
  title: Accounts Account Card Lifecycle API
  license:
    name: license
servers:
- url: https://api.sandbox.toq.io/wallet/api
  description: Simulation environment
- url: https://api.toq.io/wallet/api
  description: Production environment
tags:
- name: Card Lifecycle
paths:
  /customers/{customerId}/cards/{cardId}/activate:
    put:
      tags:
      - Card Lifecycle
      summary: Activate card
      description: 'Activates (unfreezes) a suspended card. Requires card token for activation.


        **Business Context**: Called when a cardholder or administrator wants to activate a suspended card. The activation reason is determined by the requester''s role (owner, director, or admin). Requires security code verification.'
      operationId: activateCard
      parameters:
      - $ref: '#/components/parameters/customerId'
      - $ref: '#/components/parameters/cardId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CardTokenRequest'
      responses:
        '200':
          description: Card activated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToqioResponseCardResponse'
  /customers/{customerId}/cards/{cardId}/activateOTP:
    put:
      tags:
      - Card Lifecycle
      summary: Activate card with OTP verification
      description: 'Activates a card using OTP (One-Time Password) verification for enhanced security.


        **Business Context**: Used when the banking provider requires OTP verification for card activation (e.g., first-time activation).'
      operationId: activateCardOTP
      parameters:
      - $ref: '#/components/parameters/customerId'
      - $ref: '#/components/parameters/cardId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CardOTP'
            example:
              baasOTP: '123456'
              operationId: op-12345
              userId: user-789
              cardTokenRequest:
                token: activation-token-xyz
      responses:
        '200':
          description: Card activated successfully with OTP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToqioResponseCardResponse'
        '401':
          description: Invalid OTP
  /customers/{customerId}/cards/{cardId}/cancel:
    put:
      tags:
      - Card Lifecycle
      summary: Cancel card
      description: 'Permanently cancels a card. Unlike suspend, a cancelled card cannot be reactivated.


        **Business Context**: Used when permanently deactivating a card (e.g., employee termination, compromised card). The card is removed from the available cards list in the frontend but remains in the system for audit purposes.'
      operationId: cancelCard
      parameters:
      - $ref: '#/components/parameters/customerId'
      - $ref: '#/components/parameters/cardId'
      responses:
        '200':
          description: Card cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToqioResponseCardResponse'
  /customers/{customerId}/cards/{cardId}:
    delete:
      tags:
      - Card Lifecycle
      summary: Delete card
      description: 'Permanently deletes a card from the system.


        **Business Context**: Used for complete card removal from both the system and banking provider.'
      operationId: deleteCard
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
      - name: cardId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Card deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToqioResponseCardResponse'
    get:
      tags:
      - Card Lifecycle
      summary: Get card details
      description: 'Retrieves detailed information about a specific card. Automatically syncs the card status from the banking provider to ensure consistency.


        **Business Context**: Called when viewing card details in the frontend application. Returns full card information including limits, status, and associated account details that are displayed to the user.


        **IMPORTANT - Card Limits**: The integration MUST return all card limits that are currently defined for the card (i.e. cardLimitDaily, cardLimitMonthly, cardLimitTransaction, or any custom limits). If a limit is defined for the card but not returned in the response, the system will not be able to display it correctly or will show outdated information. Only return the limits that are actually configured for this specific card - do not return limits that have not been set.'
      operationId: getCard
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
        example: cust-123
      - name: cardId
        in: path
        required: true
        schema:
          type: string
        example: card-abc123
      responses:
        '200':
          description: Card details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToqioResponseCardResponse'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers/{customerId}/cards:
    post:
      tags:
      - Card Lifecycle
      summary: Issue a new card
      description: 'Creates and issues a new physical or virtual card for a customer. This endpoint handles both debit and credit cards, supports custom card designs, delivery addresses, and limit configurations. The card will be created in the banking provider system.


        **Business Context**: Used when issuing a card to a user or creating a company card. The card details returned are displayed in the frontend application. Supports multi-company scenarios where different merchants can issue cards.'
      operationId: issueCard
      parameters:
      - name: customerId
        in: path
        description: Unique identifier of the customer (top-level entity)
        required: true
        schema:
          type: string
        example: cust-123
      requestBody:
        description: Card issuance request containing all necessary information to create a new card
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IssueCardRequest'
            examples:
              virtualDebitCard:
                summary: Issue virtual debit card for employee
                value:
                  accountId: acc-789
                  userId: user-456
                  companyId: company-123
                  physical: false
                  nameOnCard: John Doe
                  cardLimitDaily: 1000
                  cardLimitMonthly: 5000
                  cardLimitTransaction: 500
                  currency: EUR
                  cardProgramme: STANDARD
                  cardDesign: corporate-blue
              physicalCard:
                summary: Issue physical card with delivery address
                value:
                  accountId: acc-789
                  userId: user-456
                  companyId: company-123
                  physical: true
                  nameOnCard: Jane Smith
                  cardDeliveryName: Jane Smith
                  cardDeliveryAddress:
                    addressStreet: 123 Main Street
                    addressNumber: '123'
                    addressCity: London
                    addressRegion: Greater London
                    addressPostalCode: SW1A 1AA
                    addressIsoCountry: GB
                  phone:
                    countryCode: '+44'
                    number: '7700900000'
                  email: jane.smith@company.com
                  cardLimitDaily: 2000
                  cardLimitMonthly: 10000
                  cardLimitTransaction: 1000
                  lifetimeSpendLimit: 50000
                  currency: GBP
      responses:
        '200':
          description: Card issued successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToqioResponseCardResponse'
              example:
                data:
                  id: card-abc123
                  token: tok_card_xyz789
                  status: PENDING
                  provider: MODULR
                  nameOnCard: John Doe
                  truncatedPan: '4321'
                  expiryDate: 12/27
                  cardProgramme: STANDARD
                  showCustomCardDesign: true
                  activationCodeLength: 6
                code: '200'
                message: Card issued successfully
                httpStatus: 200
                requestId: 26b0f78a-79f9-426d-a20b-79841345ae51
                date: 1736935800000
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /customers/{customerId}/cards/{cardId}/suspend:
    put:
      tags:
      - Card Lifecycle
      summary: Suspend card
      description: 'Suspends (freezes) a card temporarily. The card can be reactivated later.


        **Business Context**: Called when a cardholder temporarily freezes their card (e.g., lost wallet) or when a director/admin suspends an employee''s card. Requires security code verification.'
      operationId: suspendCard
      parameters:
      - $ref: '#/components/parameters/customerId'
      - $ref: '#/components/parameters/cardId'
      responses:
        '200':
          description: Card suspended successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToqioResponseCardResponse'
  /customers/{customerId}/cards/{cardId}/update:
    put:
      tags:
      - Card Lifecycle
      summary: Update card details and limits
      description: "Updates card spending limits. This endpoint supports dynamic limit types via AdditionalParams.\n\n**Business Context**: Called when adjusting spending limits displayed in the frontend. For customers with enabled limit management, this endpoint allows updating daily, monthly, transaction, and lifetime limits. Additional custom limits (e.g., ATM limits, purchase limits) can be included via additionalProperties.\n\n**Important**: \n- This endpoint extends AdditionalParams, allowing custom limit fields to be passed. Query GET /customers/{customerId}/availableCardLimits to discover which custom limits are available in your system.\n- To update card alias, use the dedicated endpoint PUT /customers/{customerId}/cards/{cardId}/alias instead."
      operationId: updateCard
      parameters:
      - $ref: '#/components/parameters/customerId'
      - $ref: '#/components/parameters/cardId'
      requestBody:
        $ref: '#/components/requestBodies/UpdateCardRequest'
      responses:
        '200':
          description: Card updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToqioResponseCardResponse'
              example:
                data:
                  id: card-abc123
                  token: tok_card_xyz789
                  status: ACTIVE
                  provider: MODULR
                  nameOnCard: John Doe
                  truncatedPan: '4321'
                  expiryDate: 12/27
                  spend: 2500
                  limit: 5000
                code: '200'
                message: Card updated successfully
                httpStatus: 200
                requestId: 26b0f78a-79f9-426d-a20b-79841345ae51
                date: 1736935800000
  /customers/{customerId}/cards/{cardId}/alias:
    put:
      tags:
      - Card Lifecycle
      summary: Update card alias
      description: "Updates the friendly name (alias) of a specific card. This endpoint allows modifying only the card's display name without affecting other card properties.\n\n**Business Context**: Called when a user wants to rename their card for easier identification in the frontend application. The updated alias is displayed across all card views and helps users distinguish between multiple cards.\n\n**Important**: \n- This endpoint will only be called if the integration has the capability `hasCardAlias` set to `true`. If this capability is not enabled, the platform will not invoke this endpoint."
      operationId: updateCardAlias
      parameters:
      - $ref: '#/components/parameters/customerId'
      - $ref: '#/components/parameters/cardId'
      requestBody:
        description: New card alias
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCardAliasRequest'
            example:
              alias: My Business Card
      responses:
        '200':
          description: Card alias updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToqioHttpOkVoidResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /customers/{customerId}/cards/{cardId}/updateReadOnly:
    put:
      tags:
      - Card Lifecycle
      summary: Update card read-only status
      description: 'Sets a card to read-only mode, typically used for direct debit card accounts.


        **Business Context**: Used when configuring cards for specific payment methods like direct debit where the card should not allow active spending.'
      operationId: updateCardReadOnly
      parameters:
      - $ref: '#/components/parameters/customerId'
      - $ref: '#/components/parameters/cardId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                readOnly:
                  type: boolean
                  description: Whether the card should be read-only
      responses:
        '200':
          description: Card read-only status updated
components:
  schemas:
    EncryptedSecurityCode:
      type: object
      description: RSA-encrypted security verification
      properties:
        encryptedSecurityCode:
          type: string
          description: RSA-encrypted security code
        iv:
          type: string
          description: Initialization vector
        tag:
          type: string
          description: Authentication tag
    CardOTP:
      type: object
      description: OTP information for card operations
      properties:
        baasOTP:
          type: string
          description: Banking-as-a-Service OTP code
        operationId:
          type: string
          description: Unique operation identifier
        userId:
          type: string
          description: User identifier
        cardTokenRequest:
          $ref: '#/components/schemas/CardTokenRequest'
    CardResponse:
      type: object
      description: Card details response
      properties:
        id:
          type: string
          description: Unique card identifier
        token:
          type: string
          description: Card security token
        status:
          type: string
          description: Current card status
          enum:
          - PENDING
          - ACTIVE
          - SUSPENDED
          - CANCELLED
          - CLOSED
        fundingType:
          type: string
          description: Funding type of the card. Extensible; current supported values are DEBIT and CREDIT.
          enum:
          - DEBIT
          - CREDIT
        provider:
          type: string
          description: Banking provider name
        nameOnCard:
          type: string
          description: Cardholder name on the card
        truncatedPan:
          type: string
          description: Last 4 digits of PAN
        expiryDate:
          type: string
          description: Card expiry date (MM/YY)
        cardDeliveryAddress:
          $ref: '#/components/schemas/Address'
        cardDeliveryMethod:
          type: string
          description: Card delivery method
        spend:
          type: number
          format: double
          description: Total amount spent
        limit:
          type: number
          format: double
          description: Current spending limit
        cardProgramme:
          type: string
          description: Card programme/tier
        externalId:
          type: string
          description: External system identifier
        showCustomCardDesign:
          type: boolean
          description: Whether custom design is enabled
        activationCodeLength:
          type: integer
          description: Length of activation code
    ToqioHttpOkVoidResponse:
      type: object
      properties:
        data:
          type: object
          writeOnly: true
        code:
          type: string
          example: OK
        errorSeverity:
          type: string
          example: NONE
        message:
          type: string
          example: Ok
        httpStatus:
          type: integer
          format: int32
          example: 200
        requestId:
          type: string
          example: 26b0f78a-79f9-426d-a20b-79841345ae51
        date:
          type: string
          example: '2024-08-01T00:00:00.000Z'
    UpdateCardRequest:
      allOf:
      - $ref: '#/components/schemas/LimitFields'
      - type: object
        properties:
          alias:
            type: string
            maxLength: 25
            description: 'Friendly name/alias for the card (max 25 characters) - STANDARD PROPERTY. **DEPRECATED**: Use PUT /customers/{customerId}/cards/{cardId}/alias endpoint instead.'
            deprecated: true
          currency:
            type: string
            description: Currency code (ISO 4217) - STANDARD PROPERTY
          clientType:
            type: string
            enum:
            - BUSINESS
            - CONSUMER
            description: Type of client - STANDARD PROPERTY
          cardOTP:
            $ref: '#/components/schemas/CardOTP'
      description: Request to update card details. Extends LimitFields with AdditionalParams support, allowing custom limit fields to be passed. Query GET /customers/{customerId}/availableCardLimits to discover available custom limits.
      additionalProperties: true
    ToqioErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: '400'
        errorSeverity:
          type: string
          enum:
          - INFO
          - WARNING
          - ERROR
          - FATAL
          description: Severity level of the error
          example: ERROR
        message:
          type: string
          description: Human-readable error message
          example: Invalid card limit values provided
        httpStatus:
          type: integer
          description: HTTP status code
          example: 400
        debugTrace:
          type: string
          description: Debug trace information for troubleshooting
          example: ValidationException at CardService.updateCard:145
        requestId:
          type: string
          description: Unique request identifier for tracing
          example: 26b0f78a-79f9-426d-a20b-79841345ae51
        date:
          type: integer
          format: int64
          description: Timestamp as epoch milliseconds
          example: 1736935800000
        errorOrigin:
          type: string
          description: Origin system where the error occurred
          example: INTEGRATION_HUB
    LimitFields:
      type: object
      description: Base limit fields that can be set on cards. This extends AdditionalParams, allowing additional custom limit properties.
      properties:
        cardLimitDaily:
          type: integer
          format: int32
          description: Daily spending limit - STANDARD PROPERTY
        cardLimitMonthly:
          type: integer
          format: int32
          description: Monthly spending limit - STANDARD PROPERTY
        cardLimitTransaction:
          type: number
          description: Per-transaction spending limit - STANDARD PROPERTY
        lifetimeSpendLimit:
          type: number
          format: double
          description: Total lifetime spending limit - STANDARD PROPERTY
        cardMinLimitTransaction:
          type: number
          format: double
          description: Minimum transaction limit - STANDARD PROPERTY
        cardMinLimitTransactionForPhysicalBusiness:
          type: number
          format: double
          description: Minimum transaction limit for physical business cards - STANDARD PROPERTY
      additionalProperties:
        oneOf:
        - type: number
        - type: integer
        - type: string
        description: 'ADDITIONAL CUSTOM PROPERTIES: Dynamic limit properties based on system configuration. Common examples: purchasesDailyLimit, purchasesMonthlyLimit, atmDailyLimit, atmMonthlyLimit, atmOperationsLimit, purchasesOperationsLimit, and any other custom limits configured in your system.'
    Address:
      type: object
      properties:
        addressStreet:
          type: string
          description: Street name
        addressNumber:
          type: string
          description: Street number
        addressCity:
          type: string
          description: City
        addressRegion:
          type: string
          description: State/Region/County
        addressPostalCode:
          type: string
          description: Postal/ZIP code
        addressIsoCountry:
          type: string
          description: Country code (ISO 3166-1 alpha-2)
        addressRefinement:
          type: string
          description: Additional address details (apt, suite, etc.)
    IssueCardRequest:
      allOf:
      - $ref: '#/components/schemas/LimitFields'
      - type: object
        required:
        - accountId
        properties:
          accountId:
            type: string
            description: ID of the account to which the card will be linked - REQUIRED
          fundingType:
            type: string
            description: Funding type of the card. Defaults to DEBIT when omitted. Extensible; current supported values are DEBIT and CREDIT.
            enum:
            - DEBIT
            - CREDIT
            default: DEBIT
          companyId:
            type: string
            description: Company/merchant identifier
          userId:
            type: string
            description: User to whom the card will be issued
          physical:
            type: boolean
            description: Whether to issue a physical card (true) or virtual card (false)
            default: false
          nameOnCard:
            type: string
            maxLength: 21
            description: Cardholder name to be printed on the card (max 21 characters)
          cardDeliveryName:
            type: string
            description: Name for card delivery (required for physical cards)
          cardDeliveryAddress:
            $ref: '#/components/schemas/Address'
          cardBillingAddress:
            $ref: '#/components/schemas/Address'
          dateOfBirth:
            type: integer
            format: int64
            description: Cardholder date of birth (epoch timestamp)
          phone:
            $ref: '#/components/schemas/PhoneDTO'
          email:
            type: string
            format: email
            description: Cardholder email address
          firstName:
            type: string
            description: Cardholder first name
          lastName:
            type: string
            description: Cardholder last name
          cardProgramme:
            type: string
            description: Card programme/tier (e.g., STANDARD, PREMIUM)
          cardDesign:
            type: string
            description: Card design template identifier
          currency:
            type: string
            description: Card currency (ISO 4217)
          readOnly:
            type: boolean
            description: Whether the card should be read-only (for direct debit)
          billingAccountId:
            type: string
            description: Billing account ID for credit cards
      description: Request to issue a new card. Extends LimitFields to support card limit configuration during issuance.
    PhoneDTO:
      type: object
      properties:
        countryCode:
          type: string
          description: International dialing code (e.g., +44, +1)
          example: '+44'
        number:
          type: string
          description: Phone number without country code
          example: '7700900000'
    ToqioResponseCardResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CardResponse'
        code:
          type: string
          description: Response code
          example: '200'
        errorSeverity:
          type: string
          enum:
          - INFO
          - WARNING
          - ERROR
          - FATAL
          description: Severity level of the response (only present on errors)
          example: INFO
        message:
          type: string
          description: Human-readable response message
          example: Card operation completed successfully
        httpStatus:
          type: integer
          description: HTTP status code
          example: 200
        debugTrace:
          type: string
          description: Debug trace information (only present on errors)
        requestId:
          type: string
          description: Unique request identifier for tracing
          example: 26b0f78a-79f9-426d-a20b-79841345ae51
        date:
          type: integer
          format: int64
          description: Timestamp as epoch milliseconds
          example: 1736935800000
        errorOrigin:
          type: string
          description: Origin of error if applicable (only present on errors)
    UpdateCardAliasRequest:
      type: object
      required:
      - alias
      properties:
        alias:
          type: string
          maxLength: 25
          description: Friendly name/alias for the card
      description: Request to update only the card alias
    CardTokenRequest:
      type: object
      properties:
        token:
          type: string
          description: Activation token
        securityCode:
          $ref: '#/components/schemas/EncryptedSecurityCode'
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ToqioErrorResponse'
          example:
            code: '404'
            errorSeverity: ERROR
            message: Card not found
            httpStatus: 404
    BadRequest:
      description: Bad request - Invalid input parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ToqioErrorResponse'
          example:
            code: '400'
            errorSeverity: ERROR
            message: Invalid card limit values
            httpStatus: 400
            requestId: 26b0f78a-79f9-426d-a20b-79841345ae51
            date: 1736935800000
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ToqioErrorResponse'
          example:
            code: '500'
            errorSeverity: FATAL
            message: Internal server error occurred
            httpStatus: 500
            debugTrace: Stack trace information
  parameters:
    customerId:
      name: customerId
      in: path
      description: Unique identifier of the customer
      required: true
      schema:
        type: string
      example: cust-123
    cardId:
      name: cardId
      in: path
      description: Unique identifier of the card
      required: true
      schema:
        type: string
      example: card-abc123
  requestBodies:
    UpdateCardRequest:
      description: Card update request containing the card details to be updated. This object extends AdditionalParams, allowing you to pass any custom card limits that are defined in your system. To discover available custom limits, use the GET /customers/{customerId}/availableCardLimits endpoint.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateCardRequest'
          examples:
            standardUpdate:
              summary: Update standard limits
              value:
                cardLimitDaily: 1500
                cardLimitMonthly: 7000
                cardLimitTransaction: 750
                currency: EUR
                clientType: BUSINESS
            withCustomLimits:
              summary: Update with custom limit fields
              value:
                cardLimitDaily: 1500
                cardLimitMonthly: 7000
                cardLimitTransaction: 750
                currency: EUR
                clientType: BUSINESS
                lifetimeSpendLimit: 75000
                purchasesDailyLimit: 1000
                atmDailyLimit: 500
                atmOperationsLimit: 5
                purchasesOperationsLimit: 20
            withOTP:
              summary: Update requiring OTP verification
              value:
                cardLimitDaily: 2000
                cardLimitMonthly: 10000
                currency: EUR
                clientType: BUSINESS
                cardOTP:
                  baasOTP: '123456'
                  operationId: op-update-789
                  userId: user-456
  securitySchemes:
    clientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.toq.io/iam/oauth/token
          scopes: {}
x-source-pages:
- https://platform.toq.io/reference/createaccountusingpost_1
- https://platform.toq.io/reference/createdynamicaccountconfiguration
- https://platform.toq.io/reference/createproduct
- https://platform.toq.io/reference/deleteaccountstatusviaapiusingdelete
- https://platform.toq.io/reference/deleteaccountviaapiusingput
- https://platform.toq.io/reference/deletedynamicaccountconfiguration
- https://platform.toq.io/reference/getaccountsusingget
- https://platform.toq.io/reference/getaccountusingget
- https://platform.toq.io/reference/getclientaccounts
- https://platform.toq.io/reference/getcustomfaculties
- https://platform.toq.io/reference/getdynamicaccountbuttonconfiguration
- https://platform.toq.io/reference/getledgertypetexts
- https://platform.toq.io/reference/getpartnerproductsusingget_1
- https://platform.toq.io/reference/getproducts
- https://platform.toq.io/reference/updateaccountalias
- https://platform.toq.io/reference/updateaccountreadonlystatus
- https://platform.toq.io/reference/updatecustomfaculties
- https://platform.toq.io/reference/updatedynamicaccountconfiguration
- https://platform.toq.io/reference/updateledgertypetexts
- https://platform.toq.io/reference/updateproduct