openapi: 3.2.0
info:
  title: Modulr Share secure card details API
  description: Modulr API
  license:
    name: © Modulr Finance
    url: https://www.modulrfinance.com
  version: '1.0'
servers:
- url: https://api-sandbox.modulrfinance.com/api-sandbox-token
security:
- modulo_security: []
tags:
- name: Share secure card details
  description: Share secure card details operations
paths:
  /cards/{cardId}/share-secure-details/{shareSecureDetailsId}:
    get:
      tags:
      - Share secure card details
      summary: Retrieve a single share secure card details record
      description: This endpoint retrieves a specific share secure card details record for a given card and share details token id
      operationId: getShareSecureCardDetailsById
      parameters:
      - name: cardId
        in: path
        description: The ID of the card to retrieve the share secure card details for
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: shareSecureDetailsId
        in: path
        description: The id of the token whose share secure card details is being retrieved
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: includeActivity
        in: query
        description: Flag whether to include the activities of the token
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card.ShareSecureCardDetailSummaryResponse'
        '400':
          description: Invalid request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/card.MessageResponse'
        '403':
          description: Invalid permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card.ShareSecureCardDetailSummaryResponse'
      security:
      - HMAC: []
      - TOKEN: []
    put:
      tags:
      - Share secure card details
      summary: Update share secure details
      description: This endpoints allows updating the share secure card details
      operationId: updateShareSecureDetails
      parameters:
      - name: cardId
        in: path
        description: The ID of the card to update share secure card details for
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: shareSecureDetailsId
        in: path
        description: The ID of the share secure card details to update
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/card.UpdateShareSecureDetailsRequest'
        required: true
      responses:
        '204':
          description: Share secure card details successfully updated
        '400':
          description: Invalid request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/card.MessageResponse'
        '403':
          description: Invalid permissions
      security:
      - HMAC: []
      - TOKEN: []
  /cards/{cardId}/share-secure-details:
    get:
      tags:
      - Share secure card details
      summary: Retrieve share secure card details
      description: This endpoint allows the user to retrieve the share secure card details for a specific card
      operationId: getShareSecureCardDetails
      parameters:
      - name: cardId
        in: path
        description: The ID of the card to retrieve share secure card details for
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: excludeTerminated
        in: query
        description: Exclude terminated share secure card details
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: page
        in: query
        description: Page to fetch (0 indexed)
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
          minimum: 0
      - name: size
        in: query
        description: Size of page to fetch
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
          maximum: 500
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card.ShareSecureCardDetailsPageResponse'
        '400':
          description: Invalid request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/card.MessageResponse'
        '403':
          description: Invalid permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card.ShareSecureCardDetailsPageResponse'
      security:
      - HMAC: []
      - TOKEN: []
    post:
      tags:
      - Share secure card details
      summary: Share secure card details via EMAIL or RETURN methods
      description: This endpoint allows the user to create a link to share secure card details for a specific card
      operationId: createShareSecureDetails
      parameters:
      - name: cardId
        in: path
        description: The ID of the card to share secure card details for
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/card.ShareSecureCardDetailsRequest'
        required: true
      responses:
        '201':
          description: Share secure card details link successfully created
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/card.CreateShareSecureCardDetailsResponse'
        '400':
          description: Invalid request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/card.MessageResponse'
        '403':
          description: Invalid permissions
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/card.CreateShareSecureCardDetailsResponse'
      security:
      - HMAC: []
      - TOKEN: []
    delete:
      tags:
      - Share secure card details
      summary: Delete all share secure card details for a card
      description: This endpoint allows the user to delete the link to share secure card details for a specific card
      operationId: deleteShareSecureDetailsCardLink
      parameters:
      - name: cardId
        in: path
        description: The ID of the card to delete share secure card details for
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '204':
          description: Share secure card details link successfully deleted
        '400':
          description: Invalid request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/card.MessageResponse'
        '403':
          description: Invalid permissions
      security:
      - HMAC: []
      - TOKEN: []
  /cards/{cardId}/share-secure-details/{shareSecureDetailsId}/activity:
    get:
      tags:
      - Share secure card details
      summary: Retrieve share details activity of token
      description: This endpoint allows the user to retrieve the share secure card details activity for a specific share token
      operationId: getShareSecureCardDetailsTokenActivity
      parameters:
      - name: cardId
        in: path
        description: The ID of the card to retrieve share secure card details activity for
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: shareSecureDetailsId
        in: path
        description: The ID of the share secure card details to retrieve activity for
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card.ShareSecureCardDetailsTokenActivityPageResponse'
        '400':
          description: Invalid request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/card.MessageResponse'
        '403':
          description: Invalid permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card.ShareSecureCardDetailsTokenActivityPageResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /share-secure-details/{shareId}:
    delete:
      tags:
      - Share secure card details
      summary: Delete share secure card details
      description: This endpoint allows the user to delete the share secure card details for a specific Id
      operationId: deleteShareSecureDetails
      parameters:
      - name: shareId
        in: path
        description: The id of the share secure card details to delete
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '204':
          description: Share secure card details deleted successfully
        '400':
          description: Invalid request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/card.MessageResponse'
        '403':
          description: Invalid permissions
      security:
      - HMAC: []
      - TOKEN: []
components:
  schemas:
    card.ShareSecureCardDetailsResponse:
      type: object
      properties:
        id:
          type: string
        createdBy:
          type: string
        email:
          type: string
        status:
          type: string
        expiryDate:
          type: string
          format: date-time
        createdDate:
          type: string
          format: date-time
        lastRevealedDate:
          type: string
          format: date-time
        noOfAccessesLeft:
          type: integer
          format: int64
        maxAccessesAllowed:
          type: integer
          format: int64
    card.ShareSecureCardDetailsTokenActivityPageResponse:
      type: object
      properties:
        content:
          type: array
          description: List of responses on the current page
          items:
            $ref: '#/components/schemas/card.ShareSecureCardDetailsActivity'
        size:
          type: integer
          format: int32
          description: Page size
        totalSize:
          type: integer
          format: int64
          description: Total count
        page:
          type: integer
          format: int32
          description: Current page number, 0 based; i.e first-page = 0, second-page = 1
        totalPages:
          type: integer
          format: int32
          description: Total pages
      required:
      - content
      - page
      - size
      - totalPages
      - totalSize
    card.shareDetails:
      type: object
      properties:
        method:
          type: string
          description: Method to share secure card details. Can be one of RETURN or EMAIL. Will default to EMAIL if not provided.
          enum:
          - RETURN
          - EMAIL
        emails:
          type: array
          description: 'Emails to share secure card details with. Optional: Required if no method provided or if method EMAIL. Must be null for method RETURN'
          items:
            type: string
            format: email
          maxItems: 50
          minItems: 0
        noOfLinkAccesses:
          type: integer
          format: int64
          description: Number of times token/link shared will be accessible. Default of 3
        expiryDate:
          type: string
          format: date
          description: Date of expiry of the secure card details link should be default of 15 days. Must match date format of yyyy-mm-dd and be in the future.
          example: '2026-01-01'
        otherDetailsToShare:
          type: array
          description: List of other card details to share. Will be validated against fields in card response. Default is nothing.
          items:
            type: string
        message:
          type: string
          description: Message to be shared with the details. Only alphanumeric characters maximum of 200 and allowed chars -/:€$£#¢%().,!@
          maxLength: 200
          minLength: 0
          pattern: ^[a-zA-Z0-9\-/:€$£#¢%().,!@ ]*$
        externalReference:
          type: string
          description: External reference for the shared secure detail link
          maxLength: 50
          minLength: 1
          pattern: '[\w -]*'
    card.ShareSecureCardDetailSummaryResponse:
      type: object
      properties:
        id:
          type: string
        createdBy:
          type: string
        email:
          type: string
        status:
          type: string
        expiryDate:
          type: string
          format: date-time
        createdDate:
          type: string
          format: date-time
        lastRevealedDate:
          type: string
          format: date-time
        noOfAccessesLeft:
          type: integer
          format: int64
        maxAccessesAllowed:
          type: integer
          format: int64
        message:
          type: string
        externalReference:
          type: string
        otherDetails:
          type: array
          items:
            type: object
            additionalProperties: {}
        activity:
          type: array
          items:
            $ref: '#/components/schemas/card.ShareSecureCardDetailsActivity'
        customerId:
          type: string
        customerName:
          type: string
        cardScheme:
          type: string
        currency:
          type: string
    card.UpdateShareSecureDetailsRequest:
      type: object
      description: Share secure card details request
      properties:
        noOfLinkAccesses:
          type: integer
          format: int64
          description: Number of times token/link shared will be accessible. Cannot be smaller than existing number of accesses
        expiryDate:
          type: string
          format: date
          description: Date of expiry of the secure card details link.Must match date format of yyyy-mm-dd and be in the future.
          example: '2026-01-01'
        otherDetailsToShare:
          type: array
          description: List of other card details to share. Will be validated against fields in card response. Will replace existing list
          items:
            type: string
    card.ShareSecureCardDetailsActivity:
      type: object
      properties:
        action:
          type: string
        createdDate:
          type: string
          format: date-time
        createdBy:
          type: string
        shareMethod:
          type: string
          description: Method to share secure card details
          enum:
          - RETURN
          - EMAIL
    card.CreateShareSecureCardDetailsResponse:
      type: object
      description: Response for creating a share secure card details link.
      properties:
        link:
          type: string
          description: Link to secure card details. Only returned for method RETURN
        passcode:
          type: string
          description: passcode to view the secured card details. Only returned for method RETURN
    card.ShareSecureCardDetailsRequest:
      type: object
      description: Share secure card details request
      properties:
        shareCardDetails:
          $ref: '#/components/schemas/card.shareDetails'
    card.MessageResponse:
      type: object
      properties:
        field:
          type: string
        code:
          type: string
          enum:
          - GENERAL
          - BUSINESSRULE
          - MFASTATUS
          - MFAERROR
          - MFATIMEOUT
          - MFADEVICEMM
          - MFAMESSAGEINVALID
          - NOTFOUND
          - DUPLICATE
          - INVALID
          - CONNECTION
          - RETRY
          - RATELIMIT
          - PERMISSION
          - NOTACCEPTABLE
          - MFAVERIFICATION
          - TOKENEXPIRED
        errorCode:
          type: string
        message:
          type: string
        sourceService:
          type: string
    card.ShareSecureCardDetailsPageResponse:
      type: object
      properties:
        content:
          type: array
          description: List of responses on the current page
          items:
            $ref: '#/components/schemas/card.ShareSecureCardDetailsResponse'
        size:
          type: integer
          format: int32
          description: Page size
        totalSize:
          type: integer
          format: int64
          description: Total count
        page:
          type: integer
          format: int32
          description: Current page number, 0 based; i.e first-page = 0, second-page = 1
        totalPages:
          type: integer
          format: int32
          description: Total pages
      required:
      - content
      - page
      - size
      - totalPages
      - totalSize
  securitySchemes:
    modulo_security:
      type: apiKey
      name: Authorization
      in: header
    TOKEN:
      type: apiKey
      name: Authorization
      in: header
x-readme:
  proxy-enabled: false