openapi: 3.1.0
info:
  title: VGS Card Management Platform (CMP) API
  license:
    name: commercial
    url: https://www.verygoodsecurity.com/terms-and-conditions
  termsOfService: https://www.verygoodsecurity.com/terms-and-conditions
  description: |
    The VGS Card Management Platform (CMP) API.

    ### API Basics

    - All 4XX errors can be retried with appropriate changes made to the request to correct the error.
    - 502/503/504s can be retried at a later time, as these are transient errors.
    - 500s should not be retried unless advised by VGS, as these may require additional correction.

    |Status|Error Code|Description|
    |------|----|-----------|
    |400|bad-request|There is a problem with your request.  This error will potentially appear for issues with the formatting or content of your request that are not clearly identifiable by the server.|
    |401|unauthorized|Your request lacks valid authentication credentials.|
    |403|forbidden|The credentials provided do not possess the correct privileges to complete this action.|
    |415|unsupported-media-type|Your request is not using the proper media type.  Requests to this API use the JSON:API media type ('application/vnd.api+json') in the Content-Type header.|
    |422|missing-required-field|A field which is required for a valid request is missing.|
    |422|validation-failed|A field with specific validations is not valid.|
    |422|failed-dependency|The operation cannot be completed due to a dependent resource not being in the correct state. Used when attempting to interact with a Network Token that is missing or not in the ACTIVE state.|
    |500|server-error|An error occurred.  This problem is not addressable by changing the request, and the request should not be reattempted.|
    |502|bad-gateway|This error will not have the same structure as other errors, as it will be returned before the request has been processed by the application.|
    |503|service-unavailable|This error will not have the same structure as other errors, as it will be returned before the request has been processed by the application.|
    |504|gateway-timeout|This error will not have the same structure as other errors, as it will be returned before the request has been processed by the application.|
  version: doc version 2.2.9 | API version 1.0.0
servers:
  - url: https://sandbox.vgsapi.com
    description: |
      Sandbox environment server used for integration and testing. Uses network sandboxes in addition to mocked data sources.
  - url: https://vgsapi.com
    description: |
      Live environment server used for production workloads.
paths:
  /accounts:
    post:
      tags:
        - Accounts (internal)
      x-internal: true
      summary: Create an account
      security:
        - OAuth2:
            - accounts:write
      responses:
        "201":
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/RetrieveAccountResponse"
          description: The request was successful, and a new resource was created.
        "400": &400error
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: The request was invalid.
        "401": &401error
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                errors:
                  - summary: Unauthorized
                    error_code: unauthorized
                    detail: This operation requires valid authentication credentials
                    path: header.authorization
                meta:
                  observability:
                    trace_id: d03de953fee8276999edd5a2e682ffa6
                    client_id: ACa6ayoHU-am-sa-9-oF1Qj
                    vault_id: tntvhmnsawa
                    account_id: ACTfJPr7umSPZiJJckX3dMYLP
                    fingerprint: 4GqVMr6PvjLWZzJDv3XcojYVTsiicTAD9MuJZrdZHfqT6DYNG7wGbdkDCuq
          description: No credentials were provided, or the provided credentials were expired.
        "403": &403error
          content:
            application/vnd.api+json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ErrorResponse"
                  - $ref: "#/components/schemas/ErrorForbiddenResponse"
              examples:
                forbidden:
                  summary: Standard forbidden response
                  value:
                    errors:
                      - summary: Unauthorized
                        error_code: unauthorized
                        detail: This operation requires valid authentication credentials
                        path: header.authorization
                forbidden-extended:
                  summary: Forbidden with observability metadata
                  value:
                    errors:
                      - path: header.authorization
                        error_code: forbidden
                        summary: Forbidden.
                        detail: This operation requires valid authentication credentials.
                    meta:
                      observability:
                        trace_id: d03de953fee8276999edd5a2e682ffa6
                        client_id: ACa6ayoHU-am-sa-9-oF1Qj
                        vault_id: tntvhmnsawa
                        account_id: ACTfJPr7umSPZiJJckX3dMYLP
                        fingerprint: 4GqVMr6PvjLWZzJDv3XcojYVTsiicTAD9MuJZrdZHfqT6DYNG7wGbdkDCuq
                account-not-found:
                  summary: Authenticated account does not exist
                  value:
                    errors:
                      - path: .
                        summary: Account not found
                        detail: The account referenced in your authentication credentials could not be found.
                        error_code: resource-not-found
                    meta:
                      observability:
                        trace_id: d03de953fee8276999edd5a2e682ffa6
                        client_id: ACa6ayoHU-am-sa-9-oF1Qj
                        vault_id: tntvhmnsawa
                        account_id: ACTfJPr7umSPZiJJckX3dMYLP
                        fingerprint: 4GqVMr6PvjLWZzJDv3XcojYVTsiicTAD9MuJZrdZHfqT6DYNG7wGbdkDCuq
          description: Valid credentials were provided, but they do not permit access to this resource.
        "422": &422error
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: The server was unable to process the request because it contains invalid data.
      parameters:
        - $ref: "#/components/parameters/auth-header"
        - $ref: "#/components/parameters/content-type"
      description: Creates an account object from the given payload.
      operationId: createAccount
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              $ref: "#/components/schemas/AccountCreationRequest"
        required: true
        description: Create an account.
    get:
      tags:
        - Accounts (internal)
      x-internal: true
      summary: Fetch a list of accounts
      security:
        - OAuth2:
            - accounts:read
      responses:
        "200":
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/RetrieveAccountListResponse"
          description: The request was successful, and the server has returned the requested resource in the response body.
        "401": *401error
        "403": *403error
      parameters:
        - $ref: "#/components/parameters/auth-header"
        - name: filter[organization_id]
          in: query
          required: true
          schema:
            type: string
            description: Organization ID to filter accounts (e.g., filter[org_id]=ORGadasd9ads)
            example: ORGadasd9ads
      description: Fetches a list of accounts.
      operationId: fetchAListOfAccounts
  /accounts/{account-id}:
    get:
      tags:
        - Accounts (internal)
      x-internal: true
      summary: Get an account
      security:
        - OAuth2:
            - accounts:read
      responses:
        "200":
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/RetrieveAccountResponse"
          description: The request was successful, and the server has returned the requested resource in the response body.
        "401": *401error
        "403": *403error
        "404": &404error
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Resource not found.
      parameters:
        - $ref: "#/components/parameters/account-id"
        - $ref: "#/components/parameters/auth-header"
      description: Fetches the details for a specific account.
      operationId: getAccount
    put:
      tags:
        - Accounts (internal)
      x-internal: true
      summary: Update an account
      security:
        - OAuth2:
            - accounts:write
      responses:
        "200":
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/RetrieveAccountResponse"
          description: The request was successful, and the server has returned the requested resource in the response body.
        "401": *401error
        "403": *403error
        "404": *404error
        "422": *422error
      parameters:
        - $ref: "#/components/parameters/account-id"
        - $ref: "#/components/parameters/auth-header"
        - $ref: "#/components/parameters/content-type"
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              $ref: "#/components/schemas/AccountUpdateRequest"
        required: true
        description: Update an account.
      description: Updates an account.
      operationId: partiallyUpdateAnAccount
    delete:
      tags:
        - Accounts (internal)
      x-internal: true
      summary: Delete an account
      security:
        - OAuth2:
            - accounts:write
      responses:
        "204":
          content:
            application/vnd.api+json:
              schema:
                type: "null"
                title: DeleteAccountNoContent
          description: The request was successful, but there is no content to return in the response.
        "401": *401error
        "403": *403error
        "404": *404error
      parameters:
        - $ref: "#/components/parameters/account-id"
        - $ref: "#/components/parameters/auth-header"
      description: Deletes an account by ID.
      operationId: deleteAccount
  /accounts/{account-id}/configurations:
    post:
      tags:
        - Configurations (internal)
      x-internal: true
      summary: Create a configuration
      security:
        - OAuth2:
            - configurations:write
      responses:
        "201":
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/ConfigurationResource"
          description: The request was successful, and a new resource was created.
        "400": *400error
        "401": *401error
        "403": *403error
        "404": *404error
        "422": *422error
      parameters:
        - $ref: "#/components/parameters/account-id"
        - $ref: "#/components/parameters/auth-header"
        - $ref: "#/components/parameters/content-type"
      operationId: createAServiceConfiguration
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              $ref: "#/components/schemas/CreateConfigurationRequest"
        required: true
        description: ""
    get:
      tags:
        - Configurations (internal)
      x-internal: true
      summary: List configurations for an account
      security:
        - OAuth2:
            - configurations:read
      responses:
        "200":
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/ConfigurationListResponse"
          description: List of configurations retrieved successfully
        "400": *400error
        "401": *401error
        "403": *403error
        "404": *404error
      parameters:
        - $ref: "#/components/parameters/account-id"
        - $ref: "#/components/parameters/auth-header"
      operationId: listAccountConfigurations
  /accounts/{account-id}/configurations/{configuration-id}:
    get:
      tags:
        - Configurations (internal)
      x-internal: true
      summary: Get a configuration for an account
      responses:
        "200":
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/ConfigurationResource"
          description: Configuration successfully retrieved
        "400": *400error
        "401": *401error
        "403": *403error
        "404": *404error
      parameters:
        - $ref: "#/components/parameters/account-id"
        - $ref: "#/components/parameters/configuration-id"
        - $ref: "#/components/parameters/auth-header"
      operationId: fetchAServiceConfigurationEntryById
      security:
        - OAuth2:
            - account_configurations:read
    put:
      tags:
        - Configurations (internal)
      x-internal: true
      summary: Update a configuration for an account
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              $ref: "#/components/schemas/CreateConfigurationRequest"
        required: true
      responses:
        "200":
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/ConfigurationResource"
          description: Configuration successfully updated.
        "400": *400error
        "401": *401error
        "403": *403error
        "404": *404error
      parameters:
        - $ref: "#/components/parameters/account-id"
        - $ref: "#/components/parameters/configuration-id"
        - $ref: "#/components/parameters/auth-header"
        - $ref: "#/components/parameters/content-type"
      operationId: fullyUpdateAServiceConfigurationEntry
      security:
        - OAuth2:
            - account_configurations:write
    delete:
      tags:
        - Configurations (internal)
      x-internal: true
      summary: Delete a configuration
      responses:
        "204":
          content:
            application/vnd.api+json:
              schema:
                type: "null"
                title: DeleteAServiceConfigurationEntryNoContent
          description: The request was successful, but there is no content to return in the response.
        "400": *400error
        "401": *401error
        "403": *403error
        "404": *404error
      parameters:
        - $ref: "#/components/parameters/account-id"
        - $ref: "#/components/parameters/configuration-id"
        - $ref: "#/components/parameters/auth-header"
      operationId: deleteAServiceConfigurationEntry
      security:
        - OAuth2:
            - account_configurations:write
  /cards:
    post:
      tags:
        - Card Management (CMP)
      summary: Create a card
      description: |
        The Create Card Operation allows clients to register a card into the Card Management Platform (CMP) using a simple API call. This card object is linked to a specific account, supporting [account-level management](https://docs.verygoodsecurity.com/card-management/account-management) and visibility. Each card is uniquely identified by a persistent Card ID, which does not change, even if updates are made to the underlying card data. This Approach enables businesses to manage card-related features like tokenization and account updates in a centralized, consistent way. (Read more about [Duplicate Card Detection](https://docs.verygoodsecurity.com/card-management/account-management/cards#duplicate-card-detection) and [Card Fingerprint](https://docs.verygoodsecurity.com/card-management/account-management/cards#utilizing-fingerprint-with-vgs)). CMP ensures secure handling and logical grouping of cards under customer accounts, offering a scalable and organized card management experience.

        The card object also supports [user-defined metadata](https://docs.verygoodsecurity.com/card-management/account-management/cards#user-defined-metadata) through a meta object. This allows clients to attach structured, application-specific information to a card without affecting payment processing. Metadata can include any string key-value pairs to meet business needs — for example, linking a card to internal customer records, identifying the source system, or tagging the card with relevant attributes.

        PAN and Card Verification Code (CVC) tokens/aliases generated by VGS will be included as part of the response and the actual CVC can be included securely as part of a transaction. Only PCI-Compliant clients will be able to view the actual CVC, while non-PCI-Compliant clients will only be able to view an indicator that CVC was added as part of the transaction. Find more information on CVC [here](https://www.verygoodsecurity.com/docs/card-management/authentication#accessing-and-handling-cvc).
      operationId: create_card_cards_post
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              $ref: "#/components/schemas/CardResourceRequest"
            examples:
              normal:
                summary: Create a card (simple)
                description: |
                  Creates a new **card** object and begins the post-creation workflow for enabling capabilities
                value:
                  data:
                    attributes:
                      pan: "4111111111111111"
                      "cvc": "123"
                      exp_month: 4
                      exp_year: 28
              full:
                summary: Create a card (complete)
                description: A new card, with additional cardholder information.
                value:
                  data:
                    attributes:
                      pan: "4111111111111111"
                      "pan_alias": "tok_sandbox_hhyPgvvdFfFGBnyi73TfFu"
                      cvc: "123"
                      "cvc_status": "active"
                      "cvc_alias": "tok_sandbox_5XK62B8G2i1mTwoGR5o4tL"
                      exp_month: 4
                      exp_year: 28
                      cardholder:
                        name: <NAME>
                        company: A Corp, LLC
                        address:
                          address1: 123 Main St
                          address2: Suite 456
                          address3: Line 3
                          address4: Line 4
                          city: San Francisco
                          region: CA
                          postal_code: "12345"
                          country: USA
              apple_pay_dpan:
                summary: Sending dpan token and apple pay wallet
                description: |
                  Creates a new **card** with token type as DPAN and wallet type as Apple Pay
                value:
                  data:
                    attributes:
                      pan: "4111111111111111"
                      exp_month: 4
                      exp_year: 28
                      token_type: dpan
                      wallet_type: apple_pay
              google_pay_dpan:
                summary: Sending dpan token and google pay wallet
                description: |
                  Creates a new **card** with token type as DPAN and wallet type as Google Pay
                value:
                  data:
                    attributes:
                      pan: "4111111111111111"
                      exp_month: 4
                      exp_year: 28
                      token_type: dpan
                      wallet_type: google_pay
              google_pay_pan:
                summary: Sending pan token and google pay wallet
                description: |
                  Creates a new **card** with token type as PAN and wallet type as Google Pay
                value:
                  data:
                    attributes:
                      pan: "4111111111111111"
                      exp_month: 4
                      exp_year: 28
                      token_type: pan
                      wallet_type: google_pay
              user_defined_metadata:
                summary: Sending user-defined metadata
                description: |
                  Creates a new **card** with User-Defined Metadata
                value:
                  data:
                    attributes:
                      pan: "4111111111111111"
                      exp_month: 4
                      exp_year: 28
                    meta:
                      customerID: 1234
        required: true
      responses:
        "201":
          description: Card created
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/CardResourceResponse"
              examples:
                minimal:
                  value:
                    data:
                      id: CRDecqZp3xRgXU3TFmtcDdzQs
                      type: cards
                      attributes:
                        pan: "4111111111111111"
                        cvc_status: "active"
                        pan_alias: "tok_sandbox_hhyPgvvdFfFGBnyi73TfFu"
                        cvc: "123"
                        cvc_alias: "tok_sandbox_5XK62B8G2i1mTwoGR5o4tL"
                        token_type: pan
                        bin: "411111"
                        first8: "41111111"
                        last4: "1111"
                        exp_month: 5
                        exp_year: 28
                        card_fingerprint: 6TeSCB16LtyifEAmY2goxYfSk5sALriXpefzzxh29xhu
                        capabilities:
                          - network-tokens
                          - card-updates
                        created_at: "2025-08-01T00:00:00Z"
                        updated_at: "2025-08-01T00:00:00Z"
                        card_brand: "VISA"
                        card_type: "DEBIT"
                    metadata:
                      observability:
                        trace_id: 2d137f00cc53f5a9265f3b40402f7892
                        client_id: ACHwLNAA4-jc_testvault-sY8MF
                        vault_id: tnt9hg3iiwy
                        account_id: ACTrKr34UF7YyvbVPwcWqXHWn
                        fingerprint: KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM
                full:
                  value:
                    data:
                      id: CRDecqZp3xRgXU3TFmtcDdzQs
                      type: cards
                      attributes:
                        pan: "4111111111111111"
                        cvc_status: "active"
                        pan_alias: "tok_sandbox_hhyPgvvdFfFGBnyi73TfFu"
                        cvc: "123"
                        cvc_alias: "tok_sandbox_5XK62B8G2i1mTwoGR5o4tL"
                        token_type: pan
                        bin: "411111"
                        first8: "41111111"
                        last4: "1111"
                        exp_month: 5
                        exp_year: 28
                        card_fingerprint: 6TeSCB16LtyifEAmY2goxYfSk5sALriXpefzzxh29xhu
                        cardholder:
                          name: John Q. Public
                          company: Acme Co.
                          phone: "+18009998888"
                          email: "bob.smith@gmail.com"
                          address:
                            address1: 123 Main St.
                            address2: Suite 404
                            address3: Line 3
                            address4: Line 4
                            city: San Francisco
                            region: CA
                            postal_code: "80922"
                            country: US
                        capabilities:
                          - card-updates
                          - network-tokens
                        created_at: "2025-08-01T00:00:00Z"
                        updated_at: "2025-08-01T00:00:00Z"
                        card_brand: "VISA"
                        card_type: "DEBIT"
                    metadata:
                      observability:
                        trace_id: 2d137f00cc53f5a9265f3b40402f7892
                        client_id: ACHwLNAA4-jc_testvault-sY8MF
                        vault_id: tnt9hg3iiwy
                        account_id: ACTrKr34UF7YyvbVPwcWqXHWn
                        fingerprint: KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM
                pci-scope:
                  summary: pci scope
                  value:
                    data:
                      id: CRDecqZp3xRgXU3TFmtcDdzQs
                      type: cards
                      attributes:
                        pan: "4111111111111111"
                        cvc_status: "active"
                        pan_alias: "tok_sandbox_hhyPgvvdFfFGBnyi73TfFu"
                        cvc: "123"
                        cvc_alias: "tok_sandbox_5XK62B8G2i1mTwoGR5o4tL"
                        token_type: pan
                        bin: "411111"
                        first8: "41111111"
                        last4: "1111"
                        exp_month: 5
                        exp_year: 28
                        card_fingerprint: 6TeSCB16LtyifEAmY2goxYfSk5sALriXpefzzxh29xhu
                        cardholder:
                          name: John Q. Public
                          company: Acme Co.
                          phone: "+18009998888"
                          email: "bob.smith@gmail.com"
                          address:
                            address1: 123 Main St.
                            address2: Suite 404
                            address3: Line 3
                            address4: Line 4
                            city: San Francisco
                            region: CA
                            postal_code: "80922"
                            country: US
                        capabilities:
                          - card-updates
                          - network-tokens
                        created_at: "2025-08-01T00:00:00Z"
                        updated_at: "2025-08-01T00:00:00Z"
                        card_brand: "VISA"
                        card_type: "DEBIT"
                    metadata:
                      observability:
                        trace_id: 2d137f00cc53f5a9265f3b40402f7892
                        client_id: ACHwLNAA4-jc_testvault-sY8MF
                        vault_id: tnt9hg3iiwy
                        account_id: ACTrKr34UF7YyvbVPwcWqXHWn
                        fingerprint: KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM
                non_pci_scope:
                  summary: non-pci scope
                  value:
                    data:
                      id: CRDecqZp3xRgXU3TFmtcDdzQs
                      type: cards
                      attributes:
                        cvc_status: "active"
                        pan_alias: "tok_sandbox_hhyPgvvdFfFGBnyi73TfFu"
                        cvc_alias: "tok_sandbox_5XK62B8G2i1mTwoGR5o4tL"
                        token_type: pan
                        bin: "411111"
                        first8: "41111111"
                        last4: "1111"
                        exp_month: 5
                        exp_year: 28
                        card_fingerprint: 6TeSCB16LtyifEAmY2goxYfSk5sALriXpefzzxh29xhu
                        cardholder:
                          name: John Q. Public
                          company: Acme Co.
                          phone: "+18009998888"
                          email: "bob.smith@gmail.com"
                          address:
                            address1: 123 Main St.
                            address2: Suite 404
                            address3: Line 3
                            address4: Line 4
                            city: San Francisco
                            region: CA
                            postal_code: "80922"
                            country: US
                        capabilities:
                          - card-updates
                          - network-tokens
                        created_at: "2025-08-01T00:00:00Z"
                        updated_at: "2025-08-01T00:00:00Z"
                        card_brand: "VISA"
                        card_type: "DEBIT"
                    metadata:
                      observability:
                        trace_id: 2d137f00cc53f5a9265f3b40402f7892
                        client_id: ACHwLNAA4-jc_testvault-sY8MF
                        vault_id: tnt9hg3iiwy
                        account_id: ACTrKr34UF7YyvbVPwcWqXHWn
                        fingerprint: KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM
                card-attributes-advanced:
                  summary: enriched attributes
                  value:
                    data:
                      id: CRDecqZp3xRgXU3TFmtcDdzQs
                      type: cards
                      attributes:
                        pan: "4111111111111111"
                        cvc_status: "active"
                        pan_alias: "tok_sandbox_hhyPgvvdFfFGBnyi73TfFu"
                        cvc: "123"
                        cvc_alias: "tok_sandbox_5XK62B8G2i1mTwoGR5o4tL"
                        token_type: pan
                        bin: "411111"
                        first8: "41111111"
                        last4: "1111"
                        exp_month: 5
                        exp_year: 28
                        card_fingerprint: 6TeSCB16LtyifEAmY2goxYfSk5sALriXpefzzxh29xhu
                        cardholder:
                          name: John Q. Public
                          company: Acme Co.
                          phone: "+18009998888"
                          email: "bob.smith@gmail.com"
                          address:
                            address1: 123 Main St.
                            address2: Suite 404
                            address3: Line 3
                            address4: Line 4
                            city: San Francisco
                            region: CA
                            postal_code: "80922"
                            country: US
                        capabilities:
                          - card-updates
                          - network-tokens
                        created_at: "2025-08-01T00:00:00Z"
                        updated_at: "2025-08-01T00:00:00Z"
                        card_brand: "VISA"
                        card_type: "DEBIT"
                        enriched_attributes:
                          card_properties:
                            card_number_length: 16
                            card_segment_type: "PERSONAL"
                            virtual_card: false
                            prepaid_card: false
                            product_name: "CLASSIC"
                            issuer_bin: "411111"
                            country_letter_code: "US"
                            country_name: "UNITED STATES"
                            country_numeric: 840
                          card_capabilities:
                            reloadable: false
                            hsa: true
                            fsa: false
                            ebt: false
                          bank:
                            issuer_name: "U.S. EQUITY ADVANTAGE, INC."
                            issuer_phone_number: "1-800-123-4567"
                            issuer_website: "https://www.examplebank.com"
                          additional_card_brands:
                            - card_brand: "BANCONTACT"
                          interchange:
                            regulated: "N"
                    metadata:
                      observability:
                        trace_id: 2d137f00cc53f5a9265f3b40402f7892
                        client_id: ACHwLNAA4-jc_testvault-sY8MF
                        vault_id: tnt9hg3iiwy
                        account_id: ACTrKr34UF7YyvbVPwcWqXHWn
                        fingerprint: KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM
                apple_pay_dpan:
                  summary: dpan token and apple pay wallet
                  value:
                    data:
                      id: CRDecqZp3xRgXU3TFmtcDdzQs
                      type: cards
                      attributes:
                        pan: "4111111111111111"
                        cvc_status: "active"
                        token_type: dpan
                        wallet_type: apple_pay
                        bin: "411111"
                        first8: "41111111"
                        last4: "1111"
                        exp_month: 5
                        exp_year: 28
                        card_fingerprint: 6TeSCB16LtyifEAmY2goxYfSk5sALriXpefzzxh29xhu
                        created_at: "2025-08-01T00:00:00Z"
                        updated_at: "2025-08-01T00:00:00Z"
                    metadata:
                      observability:
                        trace_id: 2d137f00cc53f5a9265f3b40402f7892
                        client_id: ACHwLNAA4-jc_testvault-sY8MF
                        vault_id: tnt9hg3iiwy
                        account_id: ACTrKr34UF7YyvbVPwcWqXHWn
                        fingerprint: KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM
                google_pay_dpan:
                  summary: dpan token and google pay wallet
                  value:
                    data:
                      id: CRDecqZp3xRgXU3TFmtcDdzQs
                      type: cards
                      attributes:
                        pan: "4111111111111111"
                        cvc_status: "active"
                        token_type: dpan
                        wallet_type: google_pay
                        bin: "411111"
                        first8: "41111111"
                        last4: "1111"
                        exp_month: 5
                        exp_year: 28
                        card_fingerprint: 6TeSCB16LtyifEAmY2goxYfSk5sALriXpefzzxh29xhu
                        created_at: "2025-08-01T00:00:00Z"
                        updated_at: "2025-08-01T00:00:00Z"
                    metadata:
                      observability:
                        trace_id: 2d137f00cc53f5a9265f3b40402f7892
                        client_id: ACHwLNAA4-jc_testvault-sY8MF
                        vault_id: tnt9hg3iiwy
                        account_id: ACTrKr34UF7YyvbVPwcWqXHWn
                        fingerprint: KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM
                google_pay_pan:
                  summary: pan token and google pay wallet
                  value:
                    data:
                      id: CRDecqZp3xRgXU3TFmtcDdzQs
                      type: cards
                      attributes:
                        pan: "4111111111111111"
                        cvc_status: "active"
                        token_type: pan
                        wallet_type: google_pay
                        bin: "411111"
                        first8: "41111111"
                        last4: "1111"
                        exp_month: 5
                        exp_year: 28
                        card_fingerprint: 6TeSCB16LtyifEAmY2goxYfSk5sALriXpefzzxh29xhu
                        created_at: "2025-08-01T00:00:00Z"
                        updated_at: "2025-08-01T00:00:00Z"
                        capabilities:
                          - card-updates
                          - network-tokens
                        card_brand: "VISA"
                        card_type: "DEBIT"
                    metadata:
                      observability:
                        trace_id: 2d137f00cc53f5a9265f3b40402f7892
                        client_id: ACHwLNAA4-jc_testvault-sY8MF
                        vault_id: tnt9hg3iiwy
                        account_id: ACTrKr34UF7YyvbVPwcWqXHWn
                        fingerprint: KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM
                user_defined_metadata: &fetch_user_defined_metadata
                  summary: user-defined metadata
                  value:
                    data:
                      id: CRDecqZp3xRgXU3TFmtcDdzQs
                      type: cards
                      attributes:
                        pan: "4111111111111111"
                        cvc_status: "active"
                        token_type: pan
                        bin: "411111"
                        first8: "41111111"
                        last4: "1111"
                        exp_month: 5
                        exp_year: 28
                        card_fingerprint: 6TeSCB16LtyifEAmY2goxYfSk5sALriXpefzzxh29xhu
                        created_at: "2025-08-01T00:00:00Z"
                        updated_at: "2025-08-01T00:00:00Z"
                        capabilities:
                          - card-updates
                          - network-tokens
                        card_brand: "VISA"
                        card_type: "DEBIT"
                      meta:
                        customerID: 1234
                    metadata:
                      observability:
                        trace_id: 2d137f00cc53f5a9265f3b40402f7892
                        client_id: ACHwLNAA4-jc_testvault-sY8MF
                        vault_id: tnt9hg3iiwy
                        account_id: ACTrKr34UF7YyvbVPwcWqXHWn
                        fingerprint: KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM
        "303":
          description: The card you are trying to create already exists within the system.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/CardResourceResponse'
              example:
                data:
                  id: "CRD7yY5bq12GHv1W11tPFxcb1"
                  type: "cards"
                  attributes:
                    pan: "5100260000009208"
                    token_type: pan
                    bin: '510026'
                    first8: '51002600'
                    last4: '9208'
                    exp_month: 12
                    exp_year: 99
                    card_fingerprint: 6TeSCB16LtyifEAmY2goxYfSk5sALriXpefzzxh29xhu
                    cardholder:
                      name: "John Q. Public"
                      company: "VGS"
                      phone: "+18881112222"
                      email: "bob.smith@gmail.com"
                      address:
                        address1: "301 Test Loop"
                        city: "San Francisco"
                        region: "California"
                        postal_code: "11111"
                        country: "US"
                    created_at: "2025-08-01T00:00:00Z"
                    updated_at: "2025-08-01T00:00:00Z"
                    card_brand: "VISA"
                    card_type: "DEBIT"
                  capabilities:
                    - card-updates
                    - network-tokens
                included:
                  - type: card_update_subscriptions
                    id: CUSgkqZl3zRgXU3TFmtcDduFt
                    attributes:
                      created_at: "2019-05-15T12:30:45Z"
                      updated_at: "2019-05-16T06:00:01Z"
                      state: enrolled
                  - type: card_updates
                    id: CUPgkqZl3zRgXU3TFmtcDduFt
                    attributes:
                      received_at: "2019-05-16T06:00:01Z"
                      sent_at: "2019-05-16T06:00:01Z"
                      occurred_at: "2019-05-16T06:00:01Z"
                      event: updated
                      changed_fields:
                        - exp_month
                        - exp_year
                        - state
                      updated_values:
                        - field_name: exp_month
                          old_value: 5
                          new_values: 7
                        - field_name: exp_year
                          old_value: 24
                          new_values: 27
                        - field_name: state
                          old_value: expired
                          new_values: active
                  - type: network_tokens
                    id: NTecqZp3xRgXU3TFmtcDdzQa
                    attributes:
                      network_token: "99999900059200"
                      last4: "9200"
                      bin: "999999"
                      payment_account_reference: V0013545834930585516258022674
                      state: active
                      created_at: "2019-05-15T12:30:45Z"
                      updated_at: "2019-05-15T12:32:00Z"
                      exp_month: 12
                      exp_year: 25
                metadata:
                  observability:
                    trace_id: 2d137f00cc53f5a9265f3b40402f7892
                    client_id: ACHwLNAA4-jc_testvault-sY8MF
                    vault: tnt9hg3iiwy
                    merchant_id: MCrKr34UF7YyvbVPwcWqXHWn
                    fingerprint: >-
                      KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM
        "400":
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalid-json-format:
                  summary: Request body is not valid JSON
                  value:
                    errors:
                      - summary: Validation failed
                        detail: Invalid json format
                        error_code: validation-failed
                    meta:
                      observability:
                        trace_id: d68b9ceee1506105c28c64b80abbf1b0
                        client_id: ACiA3hktB-disc_merch_au-J7XBE
                        vault_id: tntmlqgklwl
                        account_id: ACTxG5axR5sq9DLWi8kVcxiw
                        fingerprint: 4GqVMr6PvqBbjFsbi5Syzp9oqmMcRV4VbVW7bUSNiDCxbmqSjj9TLrzNuaw
                invalid-payload:
                  summary: Payload structure or content is invalid
                  value:
                    errors:
                      - summary: Validation failed
                        detail: Invalid payload
                        error_code: validation-failed
                    meta:
                      observability:
                        trace_id: d68b9ceee1506105c28c64b80abbf1b0
                        client_id: ACiA3hktB-disc_merch_au-J7XBE
                        vault_id: tntmlqgklwl
                        account_id: ACTxG5axR5sq9DLWi8kVcxiw
                        fingerprint: 4GqVMr6PvqBbjFsbi5Syzp9oqmMcRV4VbVW7bUSNiDCxbmqSjj9TLrzNuaw
                invalid-wallet-type:
                  summary: Invalid value of wallet_type provided
                  value:
                    errors:
                      - summary: Validation failed
                        detail: Unexpected value 'provided wallet-type'
                        error_code: validation-failed
                    meta:
                      observability:
                        trace_id: d68b9ceee1506105c28c64b80abbf1b0
                        client_id: ACiA3hktB-disc_merch_au-J7XBE
                        vault_id: tntmlqgklwl
                        account_id: ACTxG5axR5sq9DLWi8kVcxiw
                        fingerprint: 4GqVMr6PvqBbjFsbi5Syzp9oqmMcRV4VbVW7bUSNiDCxbmqSjj9TLrzNuaw
                invalid-token-type:
                  summary: Invalid value of token_type provided
                  value:
                    errors:
                      - summary: Validation failed
                        detail: Unexpected value 'provided token-type'
                        error_code: validation-failed
                    meta:
                      observability:
                        trace_id: d68b9ceee1506105c28c64b80abbf1b0
                        client_id: ACiA3hktB-disc_merch_au-J7XBE
                        vault_id: tntmlqgklwl
                        account_id: ACTxG5axR5sq9DLWi8kVcxiw
                        fingerprint: 4GqVMr6PvqBbjFsbi5Syzp9oqmMcRV4VbVW7bUSNiDCxbmqSjj9TLrzNuaw
                empty-wallet-or-token-type:
                  summary: A blank value for wallet_type or token_type is not a valid enum option.
                  value:
                    errors:
                      - summary: Validation failed
                        detail: Unexpected value ''
                        error_code: validation-failed
                    meta:
                      observability:
                        trace_id: d68b9ceee1506105c28c64b80abbf1b0
                        client_id: ACiA3hktB-disc_merch_au-J7XBE
                        vault_id: tntmlqgklwl
                        account_id: ACTxG5axR5sq9DLWi8kVcxiw
                        fingerprint: 4GqVMr6PvqBbjFsbi5Syzp9oqmMcRV4VbVW7bUSNiDCxbmqSjj9TLrzNuaw
          description: The request was invalid.
        "401": *401error
        "403": *403error
        "422":
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalid-pan-size:
                  summary: PAN length is outside valid range (14-19)
                  value:
                    errors:
                      - path: data.attributes.pan
                        summary: size must be between 14 and 19
                        detail: size must be between 14 and 19
                        error_code: validation-failed
                    meta:
                      observability:
                        trace_id: 97ab24327d78ccc52b082fb0c9eed403
                        client_id: ACiAQs4Rq-cmp-test-1-dT761
                        vault_id: tntmlqtklul
                        account_id: ACTxG5aTR5sq9DLZi8kVcxiw
                        fingerprint: 4GqVMr6PvqBbjFsbi7D9U2mnz4T5cSucyfjHWiPNch2uejC2VzByBedypcw
                missing-pan:
                  summary: PAN field is required but was null
                  value:
                    errors:
                      - path: data.attributes.pan
                        summary: must not be null
                        detail: must not be null
                        error_code: validation-failed
                    meta:
                      observability:
                        trace_id: 97ab24327d78ccc52b082fb0c9eed403
                        client_id: ACiAQs4Rq-cmp-test-1-dT761
                        vault_id: tntmlqtklul
                        account_id: ACTxG5aTR5sq9DLZi8kVcxiw
                        fingerprint: 4GqVMr6PvqBbjFsbi7D9U2mnz4T5cSucyfjHWiPNch2uejC2VzByBedypcw
                invalid-pan:
                  summary: PAN contains non-numeric characters
                  value:
                    errors:
                      - path: /data/attributes/pan
                        summary: Invalid Primary Account Number
                        detail: A pan may not contain non-numeric characters.
                        error_code: validation-failed
                    meta:
                      observability:
                        trace_id: 97ab24327d78ccc52b082fb0c9eed403
                        client_id: ACiAQs4Rq-cmp-test-1-dT761
                        vault_id: tntmlqtklul
                        account_id: ACTxG5aTR5sq9DLZi8kVcxiw
                        fingerprint: 4GqVMr6PvqBbjFsbi7D9U2mnz4T5cSucyfjHWiPNch2uejC2VzByBedypcw
                invalid-cvc:
                  summary: CVC contains non-numeric characters
                  value:
                    errors:
                      - path: /data/attributes/cvc
                        summary: Invalid CVC
                        detail: A cvc may not contain non-numeric characters.
                        error_code: validation-failed
                    meta:
                      observability:
                        trace_id: 97ab24327d78ccc52b082fb0c9eed403
                        client_id: ACiAQs4Rq-cmp-test-1-dT761
                        vault_id: tntmlqtklul
                        account_id: ACTxG5aTR5sq9DLZi8kVcxiw
                        fingerprint: 4GqVMr6PvqBbjFsbi7D9U2mnz4T5cSucyfjHWiPNch2uejC2VzByBedypcw
                invalid-exp-date:
                  summary: Expiration date is too far in the past
                  value:
                    errors:
                      - path: /data/attributes/exp_year
                        summary: Invalid Expiry Month/Year
                        detail: card cannot be more than 12 months past expiration
                        error_code: validation-failed
                    meta:
                      observability:
                        trace_id: 97ab24327d78ccc52b082fb0c9eed403
                        client_id: ACiAQs4Rq-cmp-test-1-dT761
                        vault_id: tntmlqtklul
                        account_id: ACTxG5aTR5sq9DLZi8kVcxiw
                        fingerprint: 4GqVMr6PvqBbjFsbi7D9U2mnz4T5cSucyfjHWiPNch2uejC2VzByBedypcw
                missing-wallet-type:
                  summary: wallet_type is required when token_type is provided
                  value:
                    errors:
                      - path: data.meta.wallet_type
                        summary: wallet_type is missing
                        detail: wallet_type is required when token_type is provided
                        error_code: validation-failed
                    meta:
                      observability:
                        trace_id: 97ab24327d78ccc52b082fb0c9eed403
                        client_id: ACiAQs4Rq-cmp-test-1-dT761
                        vault_id: tntmlqtklul
                        account_id: ACTxG5aTR5sq9DLZi8kVcxiw
                        fingerprint: 4GqVMr6PvqBbjFsbi7D9U2mnz4T5cSucyfjHWiPNch2uejC2VzByBedypcw
                exceeding-max-metadata-items:
                  summary: Exceeding Maximum Number of Metadata Items
                  value:
                    errors:
                      - path: data.meta
                        summary: metadata is too large
                        detail: user defined metadata must not contain more than 50 items
                        error_code: validation-failed
                    meta:
                      observability:
                        trace_id: 97ab24327d78ccc52b082fb0c9eed403
                        client_id: ACiAQs4Rq-cmp-test-1-dT761
                        vault_id: tntmlqtklul
                        account_id: ACTxG5aTR5sq9DLZi8kVcxiw
                        fingerprint: 4GqVMr6PvqBbjFsbi7D9U2mnz4T5cSucyfjHWiPNch2uejC2VzByBedypcw
                exceeding-metadata-key-length:
                  summary: Metadata Key Exceeds Maximum Length
                  value:
                    errors:
                      - path: data.meta.[key truncated to first 5 characters]...
                        summary: metadata key is too long
                        detail: data.meta keys must not be longer than 50 characters
                        error_code: validation-failed
                    meta:
                      observability:
                        trace_id: 97ab24327d78ccc52b082fb0c9eed403
                        client_id: ACiAQs4Rq-cmp-test-1-dT761
                        vault_id: tntmlqtklul
                        account_id: ACTxG5aTR5sq9DLZi8kVcxiw
                        fingerprint: 4GqVMr6PvqBbjFsbi7D9U2mnz4T5cSucyfjHWiPNch2uejC2VzByBedypcw
                exceeding-metadata-value-length:
                  summary: Metadata Value Exceeds Maximum Length
                  value:
                    errors:
                      - path: data.meta.[offending key]
                        summary: metadata value is too long
                        detail: data.meta values must not be longer than 500 characters
                        error_code: validation-failed
                    meta:
                      observability:
                        trace_id: 97ab24327d78ccc52b082fb0c9eed403
                        client_id: ACiAQs4Rq-cmp-test-1-dT761
                        vault_id: tntmlqtklul
                        account_id: ACTxG5aTR5sq9DLZi8kVcxiw
                        fingerprint: 4GqVMr6PvqBbjFsbi7D9U2mnz4T5cSucyfjHWiPNch2uejC2VzByBedypcw
          description: The server was unable to process the request because it contains invalid data.
        "500": &500error
          description: Internal Server Error
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                errors:
                  - summary: Internal Server Error
                    detail: A problem has occurred with this request.
                    error_code: internal-server-error
                meta:
                  observability:
                    trace_id: 2d137f00cc53f5a9265f3b40402f7892
                    client_id: ACHwLNAA4-jc_testvault-sY8MF
                    vault: tnt9hg3iiwy
                    account_id: ACTrKr34UF7YyvbVPwcWqXHWn
                    fingerprint: KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM
        "503": &503error
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                errors:
                  - summary: Unavailable.
                    detail: Card Management Service is currently unavailable.  Please try again later.
                    error_code: service-unavailable
                meta:
                  observability:
                    trace_id: d45ced1ebf3fb9cd3cc386e9489d1b42
                    client_id: ACa6ayoHU-am-sa-9-oF1Qj
                    vault_id: tntvhmnsawa
                    account_id: ACTfJPr7umSPZiJJckX3dMYLP
                    fingerprint: 4GqVMr6PvjLWZzJDv3XcojYVTsGCJ7FnciqujuFj8bywV9vRakWy2TCK9tA
  /cards/{card_id}:
    delete:
      tags:
        - Card Management (internal)
      x-internal: true
      summary: Delete a card
      description: |
        Deletes a card by ID.
      operationId: delete_card_by_id
      security:
        - OAuth2:
            - cards:delete
      parameters:
        - name: card_id
          in: path
          required: true
          schema:
            type: string
            title: Card Id
        - $ref: "#/components/parameters/auth-header"
      responses:
        "204":
          description: Card deleted
        "401": *401error
        "403": *403error
        "404": &404cardError
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                errors:
                  path: path.card_id
                  summary: Card not found.
                  detail: No card exists with the id provided
                  error_code: card-not-found
                meta:
                  observability:
                    trace_id: 49087e7f5225892d9931dfa0d03e65a8
                    client_id: ACiA3hktB-cmp-fngrprt-1-dT761
                    vault_id: tntmlqgklwl
                    account_id: ACTxG5axR5sq9DLWi8kVcxiw
                    fingerprint: 4GqVMr6PvqBbjFsbi7D9ZinYDkZD2ve2Gr1CDhtGCGCJjmj8JCmZQqAkXLL
          description: Resource not found.
        "500": *500error
        "503": *503error
    get:
      tags:
        - Card Management (CMP)
      summary: Get a card
      description: |
        The Get Card API allows clients to retrieve details for a specific card using its unique Card ID. This includes core card metadata and any associated account updater or network token information, if applicable.
        This endpoint is useful for verifying enrollment status, accessing the current state of a card, or reviewing the card's lifecycle attributes. It provides a comprehensive snapshot of the card and its current relationships within CMP.
      operationId: get_card_by_id_cards__card_id__get
      security:
        - bearerAuth: []
      parameters:
        - name: card_id
          in: path
          required: true
          schema:
            type: string
            title: Card Id
        - name: include
          in: query
          required: false
          schema:
            type: string
            title: Comma-delimited list of resources and/or fields to include.
            description: Comma-delimited list of fields to include in the response.
          description: Comma-delimited list of fields to include in the response.
      responses:
        "200":
          description: Item requested by ID
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/CardResourceResponse"
              examples:
                minimal:
                  value:
                    data:
                      id: CRDecqZp3xRgXU3TFmtcDdzQs
                      type: cards
                      attributes:
                        pan: "4111111111111111"
                        cvc_status: "active"
                        pan_alias: "tok_sandbox_hhyPgvvdFfFGBnyi73TfFu"
                        cvc: "123"
                        cvc_alias: "tok_sandbox_5XK62B8G2i1mTwoGR5o4tL"
                        token_type: pan
                        bin: "411111"
                        first8: "41111111"
                        last4: "1111"
                        exp_month: 5
                        exp_year: 28
                        card_fingerprint: 6TeSCB16LtyifEAmY2goxYfSk5sALriXpefzzxh29xhu
                        capabilities:
                          - network-tokens
                          - card-updates
                        created_at: "2025-08-01T00:00:00Z"
                        updated_at: "2025-08-01T00:00:00Z"
                        card_brand: "VISA"
                        card_type: "DEBIT"
                    metadata:
                      observability:
                        trace_id: 2d137f00cc53f5a9265f3b40402f7892
                        client_id: ACHwLNAA4-jc_testvault-sY8MF
                        vault_id: tnt9hg3iiwy
                        account_id: ACTrKr34UF7YyvbVPwcWqXHWn
                        fingerprint: KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM
                full:
                  value:
                    data:
                      id: CRDecqZp3xRgXU3TFmtcDdzQs
                      type: cards
                      attributes:
                        pan: "4111111111111111"
                        pan_alias: "tok_sandbox_hhyPgvvdFfFGBnyi73TfFu"
                        cvc: "123"
                        cvc_status: "active"
                        cvc_alias: "tok_sandbox_5XK62B8G2i1mTwoGR5o4tL"
                        token_type: pan
                        bin: "411111"
                        first8: "41111111"
                        last4: "1111"
                        exp_month: 5
                        exp_year: 28
                        card_fingerprint: 6TeSCB16LtyifEAmY2goxYfSk5sALriXpefzzxh29xhu
                        cardholder:
                          name: John Q. Public
                          company: Acme Co.
                          phone: "+18009998888"
                          email: "bob.smith@gmail.com"
                          address:
                            address1: 123 Main St.
                            address2: Suite 404
                            address3: another row
                            address4: and another row
                            city: San Francisco
                            region: CA
                            postal_code: "80922"
                            country: US
                        capabilities:
                          - network-tokens
                          - card-updates
                        created_at: "2025-08-01T00:00:00Z"
                        updated_at: "2025-08-01T00:00:00Z"
                        card_brand: "VISA"
                        card_type: "DEBIT"
                    included:
                      - type: card_update_subscriptions
                        id: CUSgkqZl3zRgXU3TFmtcDduFt
                        attributes:
                          created_at: "2019-05-15T12:30:45Z"
                          updated_at: "2019-05-16T06:00:01Z"
                          state: enrolled
                      - type: card_updates
                        id: ae1189bf-9b9b-4ec4-9214-119fafb87b52
                        attributes:
                          changed_fields:
                            - pan
                            - exp_month
                            - exp_year
                          updated_values:
                            - field_name: pan
                              old_value: 4111111111111111
                              new_values: 411111111111123
                            - field_name: exp_month
                              old_value: 5
                              new_values: 7
                            - field_name: exp_year
                              old_value: 25
                              new_values: 27
                          event: updated
                          received_at: "2019-05-16T06:00:01Z"
                      - type: network_tokens
                        id: NTecqZp3xRgXU3TFmtcDdzQa
                        attributes:
                          network_token: "99999900059200"
                          last4: "9200"
                          bin: "999999"
                          payment_account_reference: V0013545834930585516258022674
                          state: active
                          created_at: "2019-05-15T12:30:45Z"
                          updated_at: "2019-05-15T12:32:00Z"
                          exp_month: 12
                          exp_year: 25
                        meta:
                          card_art:
                            foreground_color: "0F0F0F"
                            issuer_name: "Test-Issuer"
                            short_description: "MasterCard Test Bank"
                            long_description: "Test Bank for MasterCard MTF"
                            assets:
                              - type: CARD_SYMBOL
                                mime_type: image/png
                                width: 1536
                                height: 968
                                download_url: https://assets.calm.sandbox.verygoodsecurity.com/sandbox/calm/assets/CAacNMMShJk4pqhmY2E1N8Vz.png?Expires=1753928028&Signature=C8CEg7JxTcClvStJ17~Lqm2TmNhhYe-LwX5H3T~9tt2IEGGnLESNzyyZdDJ6U6KKQPsbK6e1iKuC1mc~V1TXaIrD3iMj47nmLFqEZs9Xku5VNw6v6RLjwMA2DshM-qBOgg2G1fZfbSAvTQBw707wCuLYuuzxPV~qS9y-pz1AM3ZbEttKO2Zg3uC82xmxfuD4tt9JZO-xsIUgPXSbkeHi~Ua7q9Y1Ikm12QIKq4plapxiEhGlzwIhP~kVQ7hZrNzukBfvuLo6mzZOvM1Miq5hysG7dmyGojrawK-dDvRhg7Nou9-Esx4jq1pTKlOQHpah1F1vTBuHQ6x53tPP0acJoQ__&Key-Pair-Id=K14FU0X3LR21JX
                              - type: DIGITAL_CARD_ART
                                mime_type: image/png
                                width: 1536
                                height: 969
                                download_url: https://assets.calm.sandbox.verygoodsecurity.com/sandbox/calm/assets/CA3JmEG1bSX88VSv4f5Gz2pG.png?Expires=1753928028&Signature=sctcfCvdeNhyTs~WJ8T6ZQD4TDYRJ24GkG~7lviSJoa11d2Q6dtGdMHqH2v9mEEO1ZcfcOCEITgjV1F3MpwIg~gsVs8n6f1jOA4BDFlJ5lynVmnrE7ImSCKJMDixYoBkMIWbwNL2IM-oZPlF2l74p8hiv5CiNz~CGxJ5OARXQFXJpSKzE6gz6aHVsO95ffcKfAZFe6qmTYKIWCq0fYfWMu1WnzUCKASVshkjIVeYINNfEfiwmfaqDLV4XPZPyPYlqHrbl0D6hx0YevnoRqgeWbDVewa3fwD4QGlSFr1FQe0AQdAibe~4nM-q7tS26BB8UVb0WkFgg0oSkJFAvF~oSA__&Key-Pair-Id=K14FU0X3LR21JX
                    metadata:
                      observability:
                        trace_id: 2d137f00cc53f5a9265f3b40402f7892
                        client_id: ACHwLNAA4-jc_testvault-sY8MF
                        vault_id: tnt9hg3iiwy
                        account_id: ACTrKr34UF7YyvbVPwcWqXHWn
                        fingerprint: KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM
                expired-event:
                  summary: expired event
                  value:
                    data:
                      id: CRDecqZp3xRgXU3TFmtcDdzQs
                      type: cards
                      attributes:
                        pan: "4111111111111111"
                        pan_alias: "tok_sandbox_hhyPgvvdFfFGBnyi73TfFu"
                        cvc: "123"
                        cvc_status: "active"
                        cvc_alias: "tok_sandbox_5XK62B8G2i1mTwoGR5o4tL"
                        token_type: pan
                        bin: "411111"
                        first8: "41111111"
                        last4: "1111"
                        exp_month: 5
                        exp_year: 28
                        card_fingerprint: 6TeSCB16LtyifEAmY2goxYfSk5sALriXpefzzxh29xhu
                        cardholder:
                          name: John Q. Public
                          company: Acme Co.
                          phone: "+18009998888"
                          email: "bob.smith@gmail.com"
                          address:
                            address1: 123 Main St.
                            address2: Suite 404
                            address3: another row
                            address4: and another row
                            city: San Francisco
                            region: CA
                            postal_code: "80922"
                            country: US
                        capabilities:
                          - network-tokens
                          - card-updates
                        created_at: "2025-08-01T00:00:00Z"
                        updated_at: "2025-08-01T00:00:00Z"
                        card_brand: "VISA"
                        card_type: "DEBIT"
                    included:
                      - type: card_update_subscriptions
                        id: CUSgkqZl3zRgXU3TFmtcDduFt
                        attributes:
                          created_at: "2019-05-15T12:30:45Z"
                          updated_at: "2019-05-16T06:00:01Z"
                          state: enrolled
                      - type: card_updates
                        id: ae1189bf-9b9b-4ec4-9214-119fafb87b52
                        attributes:
                          changed_fields:
                            - exp_month
                            - exp_year
                          updated_values:
                            - field_name: exp_month
                              old_value: 5
                              new_values: 7
                            - field_name: exp_year
                              old_value: 25
                              new_values: 27
                          event: expired
                          received_at: "2019-05-16T06:00:01Z"
                      - type: network_tokens
                        id: NTecqZp3xRgXU3TFmtcDdzQa
                        attributes:
                          network_token: "99999900059200"
                          last4: "9200"
                          bin: "999999"
                          payment_account_reference: V0013545834930585516258022674
                          state: active
                          created_at: "2019-05-15T12:30:45Z"
                          updated_at: "2019-05-15T12:32:00Z"
                          exp_month: 12
                          exp_year: 25
                    metadata:
                      observability:
                        trace_id: 2d137f00cc53f5a9265f3b40402f7892
                        client_id: ACHwLNAA4-jc_testvault-sY8MF
                        vault_id: tnt9hg3iiwy
                        account_id: ACTrKr34UF7YyvbVPwcWqXHWn
                        fingerprint: KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM
                pci-scope:
                  summary: pci scope
                  value:
                    data:
                      id: CRDecqZp3xRgXU3TFmtcDdzQs
                      type: cards
                      attributes:
                        pan: "4111111111111111"
                        pan_alias: "tok_sandbox_hhyPgvvdFfFGBnyi73TfFu"
                        cvc: "123"
                        cvc_status: "active"
                        cvc_alias: "tok_sandbox_5XK62B8G2i1mTwoGR5o4tL"
                        token_type: pan
                        bin: "411111"
                        first8: "41111111"
                        last4: "1111"
                        exp_month: 5
                        exp_year: 28
                        card_fingerprint: 6TeSCB16LtyifEAmY2goxYfSk5sALriXpefzzxh29xhu
                        cardholder:
                          name: John Q. Public
                          company: Acme Co.
                          phone: "+18009998888"
                          email: "bob.smith@gmail.com"
                          address:
                            address1: 123 Main St.
                            address2: Suite 404
                            address3: another row
                            address4: and another row
                            city: San Francisco
                            region: CA
                            postal_code: "80922"
                            country: US
                        capabilities:
                          - network-tokens
                          - card-updates
                        created_at: "2025-08-01T00:00:00Z"
                        updated_at: "2025-08-01T00:00:00Z"
                        card_brand: "VISA"
                        card_type: "DEBIT"
                    included:
                      - type: card_update_subscriptions
                        id: CUSgkqZl3zRgXU3TFmtcDduFt
                        attributes:
                          created_at: "2019-05-15T12:30:45Z"
                          updated_at: "2019-05-16T06:00:01Z"
                          state: enrolled
                      - type: card_updates
                        id: ae1189bf-9b9b-4ec4-9214-119fafb87b52
                        attributes:
                          changed_fields:
                            - pan
                            - exp_year
                          updated_values:
                            - field_name: pan
                              old_value: 4111111111111111
                              new_values: 411111111111123
                            - field_name: exp_year
                              old_value: 25
                              new_values: 27
                          event: updated
                          received_at: "2019-05-16T06:00:01Z"
                      - type: network_tokens
                        id: NTecqZp3xRgXU3TFmtcDdzQa
                        attributes:
                          network_token: "99999900059200"
                          last4: "9200"
                          bin: "999999"
                          payment_account_reference: V0013545834930585516258022674
                          state: active
                          created_at: "2019-05-15T12:30:45Z"
                          updated_at: "2019-05-15T12:32:00Z"
                          exp_month: 12
                          exp_year: 25
                    metadata:
                      observability:
                        trace_id: 2d137f00cc53f5a9265f3b40402f7892
                        client_id: ACHwLNAA4-jc_testvault-sY8MF
                        vault_id: tnt9hg3iiwy
                        account_id: ACTrKr34UF7YyvbVPwcWqXHWn
                        fingerprint: KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM
                non_pci_scope:
                  summary: non-pci scope
                  value:
                    data:
                      id: CRDecqZp3xRgXU3TFmtcDdzQs
                      type: cards
                      attributes:
                        pan_alias: "tok_sandbox_hhyPgvvdFfFGBnyi73TfFu"
                        cvc_status: "active"
                        cvc_alias: "tok_sandbox_5XK62B8G2i1mTwoGR5o4tL"
                        token_type: pan
                        bin: "411111"
                        first8: "41111111"
                        last4: "1111"
                        exp_month: 5
                        exp_year: 28
                        card_fingerprint: 6TeSCB16LtyifEAmY2goxYfSk5sALriXpefzzxh29xhu
                        cardholder:
                          name: John Q. Public
                          company: Acme Co.
                          phone: "+18009998888"
                          email: "bob.smith@gmail.com"
                          address:
                            address1: 123 Main St.
                            address2: Suite 404
                            address3: another row
                            address4: and another row
                            city: San Francisco
                            region: CA
                            postal_code: "80922"
                            country: US
                        capabilities:
                          - network-tokens
                          - card-updates
                        created_at: "2025-08-01T00:00:00Z"
                        updated_at: "2025-08-01T00:00:00Z"
                        card_brand: "VISA"
                        card_type: "DEBIT"
                    included:
                      - type: card_update_subscriptions
                        id: CUSgkqZl3zRgXU3TFmtcDduFt
                        attributes:
                          created_at: "2019-05-15T12:30:45Z"
                          updated_at: "2019-05-16T06:00:01Z"
                          state: enrolled
                      - type: card_updates
                        id: CUPgkqZl3zRgXU3TFmtcDduFt
                        attributes:
                          received_at: "2019-05-16T06:00:01Z"
                          sent_at: "2019-05-16T06:00:01Z"
                          occurred_at: "2019-05-16T06:00:01Z"
                          event: updated
                          changed_fields:
                            - exp_month
                            - exp_year
                            - state
                          updated_values:
                            - field_name: exp_month
                              old_value: 5
                              new_values: 7
                            - field_name: exp_year
                              old_value: 24
                              new_values: 27
                            - field_name: state
                              old_value: expired
                              new_values: active
                      - type: network_tokens
                        id: NTecqZp3xRgXU3TFmtcDdzQa
                        attributes:
                          network_token: "99999900059200"
                          last4: "9200"
                          bin: "999999"
                          payment_account_reference: V0013545834930585516258022674
                          state: active
                          created_at: "2019-05-15T12:30:45Z"
                          updated_at: "2019-05-15T12:32:00Z"
                          exp_month: 12
                          exp_year: 25
                        meta:
                          card_art:
                            assets:
                              - type: CARD_SYMBOL
                                mime_type: image/png
                                width: 1536
                                height: 968
                                download_url: https://assets.calm.sandbox.verygoodsecurity.com/sandbox/calm/assets/CAacNMMShJk4pqhmY2E1N8Vz.png?Expires=1753928028&Signature=C8CEg7JxTcClvStJ17~Lqm2TmNhhYe-LwX5H3T~9tt2IEGGnLESNzyyZdDJ6U6KKQPsbK6e1iKuC1mc~V1TXaIrD3iMj47nmLFqEZs9Xku5VNw6v6RLjwMA2DshM-qBOgg2G1fZfbSAvTQBw707wCuLYuuzxPV~qS9y-pz1AM3ZbEttKO2Zg3uC82xmxfuD4tt9JZO-xsIUgPXSbkeHi~Ua7q9Y1Ikm12QIKq4plapxiEhGlzwIhP~kVQ7hZrNzukBfvuLo6mzZOvM1Miq5hysG7dmyGojrawK-dDvRhg7Nou9-Esx4jq1pTKlOQHpah1F1vTBuHQ6x53tPP0acJoQ__&Key-Pair-Id=K14FU0X3LR21JX
                              - type: DIGITAL_CARD_ART
                                mime_type: image/png
                                width: 1536
                                height: 969
                                download_url: https://assets.calm.sandbox.verygoodsecurity.com/sandbox/calm/assets/CA3JmEG1bSX88VSv4f5Gz2pG.png?Expires=1753928028&Signature=sctcfCvdeNhyTs~WJ8T6ZQD4TDYRJ24GkG~7lviSJoa11d2Q6dtGdMHqH2v9mEEO1ZcfcOCEITgjV1F3MpwIg~gsVs8n6f1jOA4BDFlJ5lynVmnrE7ImSCKJMDixYoBkMIWbwNL2IM-oZPlF2l74p8hiv5CiNz~CGxJ5OARXQFXJpSKzE6gz6aHVsO95ffcKfAZFe6qmTYKIWCq0fYfWMu1WnzUCKASVshkjIVeYINNfEfiwmfaqDLV4XPZPyPYlqHrbl0D6hx0YevnoRqgeWbDVewa3fwD4QGlSFr1FQe0AQdAibe~4nM-q7tS26BB8UVb0WkFgg0oSkJFAvF~oSA__&Key-Pair-Id=K14FU0X3LR21JX
                    metadata:
                      observability:
                        trace_id: 2d137f00cc53f5a9265f3b40402f7892
                        client_id: ACHwLNAA4-jc_testvault-sY8MF
                        vault_id: tnt9hg3iiwy
                        account_id: ACTrKr34UF7YyvbVPwcWqXHWn
                        fingerprint: KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM
                card-attributes-advanced:
                  summary: enriched attributes
                  value:
                    data:
                      id: CRDecqZp3xRgXU3TFmtcDdzQs
                      type: cards
                      attributes:
                        pan: "4111111111111111"
                        pan_alias: "tok_sandbox_hhyPgvvdFfFGBnyi73TfFu"
                        cvc: "123"
                        cvc_status: "active"
                        cvc_alias: "tok_sandbox_5XK62B8G2i1mTwoGR5o4tL"
                        token_type: pan
                        bin: "411111"
                        first8: "41111111"
                        last4: "1111"
                        exp_month: 5
                        exp_year: 28
                        card_fingerprint: 6TeSCB16LtyifEAmY2goxYfSk5sALriXpefzzxh29xhu
                        cardholder:
                          name: John Q. Public
                          company: Acme Co.
                          phone: "+18009998888"
                          email: "bob.smith@gmail.com"
                          address:
                            address1: 123 Main St.
                            address2: Suite 404
                            address3: another row
                            address4: and another row
                            city: San Francisco
                            region: CA
                            postal_code: "80922"
                            country: US
                        capabilities:
                          - network-tokens
                          - card-updates
                        created_at: "2025-08-01T00:00:00Z"
                        updated_at: "2025-08-01T00:00:00Z"
                        card_brand: "VISA"
                        card_type: "DEBIT"
                        enriched_attributes:
                          card_properties:
                            card_number_length: 16
                            card_segment_type: "PERSONAL"
                            virtual_card: false
                            prepaid_card: false
                            product_name: "CLASSIC"
                            issuer_bin: "411111"
                            country_letter_code: "US"
                            country_name: "UNITED STATES"
                            country_numeric: 840
                          card_capabilities:
                            reloadable: false
                            hsa: true
                            fsa: false
                            ebt: false
                          bank:
                            issuer_name: "U.S. EQUITY ADVANTAGE, INC."
                            issuer_phone_number: "1-800-123-4567"
                            issuer_website: "https://www.examplebank.com"
                          additional_card_brands:
                            - card_brand: "BANCONTACT"
                          interchange:
                            regulated: "N"
                    included:
                      - type: card_update_subscriptions
                        id: CUSgkqZl3zRgXU3TFmtcDduFt
                        attributes:
                          created_at: "2019-05-15T12:30:45Z"
                          updated_at: "2019-05-16T06:00:01Z"
                          state: enrolled
                      - type: card_updates
                        id: ae1189bf-9b9b-4ec4-9214-119fafb87b52
                        attributes:
                          changed_fields:
                            - exp_year
                          updated_values:
                            - field_name: exp_year
                              old_value: 25
                              new_values: 27
                          event: updated
                          received_at: "2019-05-16T06:00:01Z"
                      - type: network_tokens
                        id: NTecqZp3xRgXU3TFmtcDdzQa
                        attributes:
                          network_token: "99999900059200"
                          last4: "9200"
                          bin: "999999"
                          payment_account_reference: V0013545834930585516258022674
                          state: active
                          created_at: "2019-05-15T12:30:45Z"
                          updated_at: "2019-05-15T12:32:00Z"
                          exp_month: 12
                          exp_year: 25
                    metadata:
                      observability:
                        trace_id: 2d137f00cc53f5a9265f3b40402f7892
                        client_id: ACHwLNAA4-jc_testvault-sY8MF
                        vault_id: tnt9hg3iiwy
                        account_id: ACTrKr34UF7YyvbVPwcWqXHWn
                        fingerprint: KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM
                apple_pay_dpan:
                  summary: dpan token and apple pay wallet
                  value:
                    data:
                      id: CRDecqZp3xRgXU3TFmtcDdzQs
                      type: cards
                      attributes:
                        pan: "4111111111111111"
                        cvc_status: "active"
                        token_type: dpan
                        wallet_type: apple_pay
                        bin: "411111"
                        first8: "41111111"
                        last4: "1111"
                        exp_month: 5
                        exp_year: 28
                        card_fingerprint: 6TeSCB16LtyifEAmY2goxYfSk5sALriXpefzzxh29xhu
                        created_at: "2025-08-01T00:00:00Z"
                        updated_at: "2025-08-01T00:00:00Z"
                    metadata:
                      observability:
                        trace_id: 2d137f00cc53f5a9265f3b40402f7892
                        client_id: ACHwLNAA4-jc_testvault-sY8MF
                        vault_id: tnt9hg3iiwy
                        account_id: ACTrKr34UF7YyvbVPwcWqXHWn
                        fingerprint: KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM
                google_pay_dpan:
                  summary: dpan token and google pay wallet
                  value:
                    data:
                      id: CRDecqZp3xRgXU3TFmtcDdzQs
                      type: cards
                      attributes:
                        pan: "4111111111111111"
                        cvc_status: "active"
                        token_type: dpan
                        wallet_type: google_pay
                        bin: "411111"
                        first8: "41111111"
                        last4: "1111"
                        exp_month: 5
                        exp_year: 28
                        card_fingerprint: 6TeSCB16LtyifEAmY2goxYfSk5sALriXpefzzxh29xhu
                        created_at: "2025-08-01T00:00:00Z"
                        updated_at: "2025-08-01T00:00:00Z"
                    metadata:
                      observability:
                        trace_id: 2d137f00cc53f5a9265f3b40402f7892
                        client_id: ACHwLNAA4-jc_testvault-sY8MF
                        vault_id: tnt9hg3iiwy
                        account_id: ACTrKr34UF7YyvbVPwcWqXHWn
                        fingerprint: KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM
                google_pay_pan:
                  summary: pan token and google pay wallet
                  value:
                    data:
                      id: CRDecqZp3xRgXU3TFmtcDdzQs
                      type: cards
                      attributes:
                        pan: "4111111111111111"
                        cvc_status: "active"
                        token_type: pan
                        wallet_type: google_pay
                        bin: "411111"
                        first8: "41111111"
                        last4: "1111"
                        exp_month: 5
                        exp_year: 28
                        card_fingerprint: 6TeSCB16LtyifEAmY2goxYfSk5sALriXpefzzxh29xhu
                        created_at: "2025-08-01T00:00:00Z"
                        updated_at: "2025-08-01T00:00:00Z"
                        capabilities:
                          - card-updates
                          - network-tokens
                        card_brand: "VISA"
                        card_type: "DEBIT"
                    metadata:
                      observability:
                        trace_id: 2d137f00cc53f5a9265f3b40402f7892
                        client_id: ACHwLNAA4-jc_testvault-sY8MF
                        vault_id: tnt9hg3iiwy
                        account_id: ACTrKr34UF7YyvbVPwcWqXHWn
                        fingerprint: KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM
                user_defined_metadata: *fetch_user_defined_metadata
        "400": *400error
        "401": *401error
        "403": *403error
        "404": *404cardError
        "500": *500error
        "503": *503error
  /cards/{card_id}/card-update-subscriptions:
    post:
      tags:
        - Account Updater
      summary: Subscribe
      description: |
        To begin receiving automated updates for a card, it must be enrolled in account updater using the **Subscribe** operation. This API enables continuous tracking of card status with the issuing network. If the card is already subscribed, the system will automatically skip re-enrollment.
        Subscribing ensures that your application will receive updates on card replacements, expiration changes, and other important lifecycle events, keeping your records accurate without customer input.
      operationId: subscribe_card_for_au
      security:
        - bearerAuth: []
      parameters:
        - name: card_id
          in: path
          required: true
          schema:
            type: string
            title: Card Id
      responses:
        "201": &cardSubscribedResponse
          description: Card subscription details
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/CardUpdateSubscriptionResourceResponse"
              example:
                data:
                  type: card_update_subscriptions
                  id: CUS9ecrtBiwFpyT4qCtStYp4e
                  attributes:
                    created_at: 2025-01-10T18:23:48.96686
                    state: enrolled
                    updated_at: 2025-01-10T18:23:48.966869
        "200": *cardSubscribedResponse
        "400":
          description: The request was invalid.
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                errors:
                  - summary: Account updater request failed.
                    detail: Invalid json format
                    error_code: validation-failed
                meta:
                  observability:
                    trace_id: d68b9ceee1506105c28c64b80abbf1b0
                    client_id: ACiA3hktB-disc_merch_au-J7XBE
                    vault_id: tntmlqgklwl
                    account_id: ACTxG5axR5sq9DLWi8kVcxiw
                    fingerprint: 4GqVMr6PvqBbjFsbi5Syzp9oqmMcRV4VbVW7bUSNiDCxbmqSjj9TLrzNuaw
        "403":
          description: Valid credentials were provided, but they do not permit access to this resource.
          content:
            application/vnd.api+json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ErrorResponse"
                  - $ref: "#/components/schemas/ErrorForbiddenResponse"
              examples:
                forbidden:
                  summary: Basic forbidden response
                  value:
                    errors:
                      - status: 403
                        title: Forbidden
                        details: Access Denied
                forbidden-extended:
                  summary: Forbidden with authorization context and trace metadata
                  value:
                    errors:
                      - path: header.authorization
                        errorCode: forbidden
                        summary: Forbidden.
                        detail: This operation requires valid authentication credentials.
                    meta:
                      observability:
                        trace_id: d03de953fee8276999edd5a2e682ffa6
                        client_id: ACa6ayoHU-am-sa-9-oF1Qj
                        vault_id: tntvhmnsawa
                        account_id: ACTfJPr7umSPZiJJckX3dMYLP
                        fingerprint: 4GqVMr6PvjLWZzJDv3XcojYVTsiicTAD9MuJZrdZHfqT6DYNG7wGbdkDCuq
                account-not-found:
                  summary: Account referenced in auth token is missing
                  value:
                    errors:
                      - path: .
                        summary: Account not found
                        detail: The account referenced in your authentication credentials could not be found.
                        error_code: resource-not-found
                    meta:
                      observability:
                        trace_id: d03de953fee8276999edd5a2e682ffa6
                        client_id: ACa6ayoHU-am-sa-9-oF1Qj
                        vault_id: tntvhmnsawa
                        account_id: ACTfJPr7umSPZiJJckX3dMYLP
                        fingerprint: 4GqVMr6PvjLWZzJDv3XcojYVTsiicTAD9MuJZrdZHfqT6DYNG7wGbdkDCuq
                not_enabled:
                  summary: Required service (e.g., CARD_UPDATER) is not enabled
                  value:
                    errors:
                      - detail: The CARD_UPDATER service is not enabled
                        summary: Service is not enabled
                        error_code: service-not-enabled
                    meta:
                      observability:
                        trace_id: d03de953fee8276999edd5a2e682ffa6
                        client_id: ACa6ayoHU-am-sa-9-oF1Qj
                        vault_id: tntvhmnsawa
                        account_id: ACTfJPr7umSPZiJJckX3dMYLP
                        fingerprint: 4GqVMr6PvjLWZzJDv3XcojYVTsiicTAD9MuJZrdZHfqT6DYNG7wGbdkDCuq
        "404": *404cardError
        "500": *500error
        "503": *503error
    delete:
      tags:
        - Account Updater
      summary: Unsubscribe
      description: |
        When a card is no longer needed for Account Update tracking, you can unsubscribe it from account updater using a DELETE call to the Card API. This removes account updater tracking from the specified card, and the system will no longer request or deliver updates for it.
        After unsubscription:
          - The account updater object is removed from the card’s metadata.
          - No future updates will be received for this card.
          - The card is considered unenrolled from account updater in the CMP system.
        This is useful when cards are retired, no longer relevant for recurring billing, or should be managed manually.
      operationId: unsubscribe_card_by_id
      security:
        - bearerAuth: []
      parameters:
        - name: card_id
          in: path
          required: true
          schema:
            type: string
            title: Card Id
      responses:
        "204":
          description: Card unsubscribed
        "401": *401error
        "403": *403error
        "404": *404cardError
        "424": &424error
          description: Underlying service experiences high load
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                errors:
                  - summary: Busy.
                    detail: Please try again later.
                    error_code: service-busy
                meta:
                  observability:
                    trace_id: d45ced1ebf3fb9cd3cc386e9489d1b42
                    client_id: ACa6ayoHU-am-sa-9-oF1Qj
                    vault_id: tntvhmnsawa
                    account_id: ACTfJPr7umSPZiJJckX3dMYLP
                    fingerprint: 4GqVMr6PvjLWZzJDv3XcojYVTsGCJ7FnciqujuFj8bywV9vRakWy2TCK9tA
        "500": *500error
        "503": *503error
  /cards/{card_id}/check:
    post:
      tags:
        - Account Updater
      summary: On-Demand updates
      description: |
        The On-Demand Card Updates API offers a stateless, real-time way to check for the latest card information without enrolling the card in account updater. This feature supports Visa and Mastercard only and is ideal for one-time update lookups.
        For American Express (AMEX) and Discover, updates are only available for cards that have already been enrolled in account updater via VGS. This API is useful for verifying card updates without committing to long-term account updater tracking. It returns the most current data available at the time of the request, helping businesses make decisions in real time without the overhead of subscription.
      operationId: check_card_for_updates
      security:
        - bearerAuth: []
      parameters:
        - name: card_id
          in: path
          required: true
          schema:
            type: string
            title: Card Id
      responses:
        "200":
          description: Card updates
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/CardCheckResourceResponse"
              examples:
                updated:
                  summary: Card data successfully updated
                  value:
                    data:
                      type: card_updates
                      attributes:
                        updated_values:
                          - field_name: pan
                            old_value: 4211111111111112
                            new_value: 4311111111111113
                          - field_name: exp_month
                            old_value: 4
                            new_value: 6
                          - field_name: exp_year
                            old_value: 24
                            new_value: 33
                        event: updated
        "400":
          description: The request was invalid.
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                errors:
                  - detail: A known error
                    summary: Account updater request failed.
                    error_code: something-happened
                meta:
                  observability:
                    trace_id: d03de953fee8276999edd5a2e682ffa6
                    client_id: ACa6ayoHU-am-sa-9-oF1Qj
                    vault_id: tntvhmnsawa
                    account_id: ACTfJPr7umSPZiJJckX3dMYLP
                    fingerprint: 4GqVMr6PvjLWZzJDv3XcojYVTsiicTAD9MuJZrdZHfqT6DYNG7wGbdkDCuq
        "401": *401error
        "403":
          description: Valid credentials were provided, but they do not permit access to this resource.
          content:
            application/vnd.api+json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ErrorResponse"
                  - $ref: "#/components/schemas/ErrorForbiddenResponse"
              examples:
                forbidden:
                  summary: Basic forbidden response
                  value:
                    errors:
                      - status: 403
                        title: Forbidden
                        details: Access Denied
                forbidden-extended:
                  summary: Forbidden with authorization header and trace context
                  value:
                    errors:
                      - path: header.authorization
                        error_code: forbidden
                        summary: Forbidden.
                        detail: This operation requires valid authentication credentials.
                    meta:
                      observability:
                        trace_id: d03de953fee8276999edd5a2e682ffa6
                        client_id: ACa6ayoHU-am-sa-9-oF1Qj
                        vault_id: tntvhmnsawa
                        account_id: ACTfJPr7umSPZiJJckX3dMYLP
                        fingerprint: 4GqVMr6PvjLWZzJDv3XcojYVTsiicTAD9MuJZrdZHfqT6DYNG7wGbdkDCuq
                account-not-found:
                  summary: Authenticated account could not be found
                  value:
                    errors:
                      - path: .
                        summary: Account not found
                        detail: The account referenced in your authentication credentials could not be found.
                        error_code: resource-not-found
                    meta:
                      observability:
                        trace_id: d03de953fee8276999edd5a2e682ffa6
                        client_id: ACa6ayoHU-am-sa-9-oF1Qj
                        vault_id: tntvhmnsawa
                        account_id: ACTfJPr7umSPZiJJckX3dMYLP
                        fingerprint: 4GqVMr6PvjLWZzJDv3XcojYVTsiicTAD9MuJZrdZHfqT6DYNG7wGbdkDCuq
                not-enabled:
                  summary: Required service is not enabled (e.g., CARD_UPDATER)
                  value:
                    errors:
                      - detail: The CARD_UPDATER service is not enabled
                        summary: Service is not enabled
                        error_code: service-not-enabled
                    meta:
                      observability:
                        trace_id: d03de953fee8276999edd5a2e682ffa6
                        client_id: ACa6ayoHU-am-sa-9-oF1Qj
                        vault_id: tntvhmnsawa
                        account_id: ACTfJPr7umSPZiJJckX3dMYLP
                        fingerprint: 4GqVMr6PvjLWZzJDv3XcojYVTsiicTAD9MuJZrdZHfqT6DYNG7wGbdkDCuq
        "404": *404cardError
        "424": *424error
        "500": *500error
        "503": *503error
  /cards/{card_id}/network-tokens:
    post:
      tags:
        - Network Tokens
      summary: Provision
      description: |
        When Network Tokens are enabled for an account, VGS automatically provisions a token for each card stored. This provisioned token is mapped to the Card ID and kept in sync with the card’s network lifecycle.
        As the card is updated or reissued, network token metadata is refreshed, enabling businesses to maintain valid and up-to-date payment credentials with no extra effort. Provisioning Network Tokens offers merchants a future-proof, secure foundation for handling customer payments. The provisioning is skipped if there is an active network token already exists for the card. This provisioning process is applicable regardless of the network token type - Card on File or Ecommerce Network Token.
      operationId: provision_nt_for_card
      security:
        - bearerAuth: []
      parameters:
        - name: card_id
          in: path
          required: true
          schema:
            type: string
            title: Card Id
      responses:
        "201": &networkTokenCreatedResponse
          description: Card's network token
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/NetworkTokenResourceResponse"
              example:
                data:
                  type: network_tokens
                  id: NTKu5rM55z4PNMLW9Rqrhd466
                  attributes:
                    payment_account_reference: V0010013025209632906568838169
                    network_token: 5580043943638177
                    last4: 8177
                    bin: 558004
                    exp_month: 4
                    exp_year: 26
                    created_at: 2025-01-10T17:56:12.783411
                    updated_at: 2025-01-10T17:56:12.783429
                    state: active
        "200": *networkTokenCreatedResponse
        "400":
          description: The request was invalid.
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                errors:
                  - detail: Invalid json format
                    summary: Network token request failed.
                    error_code: validation-failed
        "401": *401error
        "403":
          description: Valid credentials were provided, but they do not permit access to this resource.
          content:
            application/vnd.api+json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ErrorResponse"
                  - $ref: "#/components/schemas/ErrorForbiddenResponse"
              examples:
                forbidden:
                  summary: Basic forbidden error
                  value:
                    errors:
                      - status: 403
                        title: Forbidden
                        details: Access Denied
                forbidden-extended:
                  summary: Forbidden error with authorization header context and observability metadata
                  value:
                    errors:
                      - path: header.authorization
                        error_code: forbidden
                        summary: Forbidden.
                        detail: This operation requires valid authentication credentials.
                    meta:
                      observability:
                        trace_id: d03de953fee8276999edd5a2e682ffa6
                        client_id: ACa6ayoHU-am-sa-9-oF1Qj
                        vault_id: tntvhmnsawa
                        account_id: ACTfJPr7umSPZiJJckX3dMYLP
                        fingerprint: 4GqVMr6PvjLWZzJDv3XcojYVTsiicTAD9MuJZrdZHfqT6DYNG7wGbdkDCuq
                account-not-found:
                  summary: Authentication credentials reference a missing account
                  value:
                    errors:
                      - path: .
                        summary: Account not found
                        detail: The account referenced in your authentication credentials could not be found.
                        error_code: resource-not-found
                    meta:
                      observability:
                        trace_id: d03de953fee8276999edd5a2e682ffa6
                        client_id: ACa6ayoHU-am-sa-9-oF1Qj
                        vault_id: tntvhmnsawa
                        account_id: ACTfJPr7umSPZiJJckX3dMYLP
                        fingerprint: 4GqVMr6PvjLWZzJDv3XcojYVTsiicTAD9MuJZrdZHfqT6DYNG7wGbdkDCuq
                not-enabled:
                  summary: NETWORK_TOKENS service is not enabled
                  value:
                    errors:
                      - detail: The NETWORK_TOKENS service is not enabled.
                        summary: Service is not enabled
                        error_code: service-not-enabled
                    meta:
                      observability:
                        trace_id: d03de953fee8276999edd5a2e682ffa6
                        client_id: ACa6ayoHU-am-sa-9-oF1Qj
                        vault_id: tntvhmnsawa
                        account_id: ACTfJPr7umSPZiJJckX3dMYLP
                        fingerprint: 4GqVMr6PvjLWZzJDv3XcojYVTsiicTAD9MuJZrdZHfqT6DYNG7wGbdkDCuq
        "404": *404cardError
        "500": *500error
        "503": *503error
    delete:
      tags:
        - Network Tokens
      summary: Delete
      description: |
        The Delete Network Token operation allows you to deactivate a previously provisioned network token on the card.
        Once deleted -
          - The Network Token becomes invalid and stops receiving updates.
          - The card’s network token data is removed from the CMP system.
          - Network Token-based operations like cryptogram generation (e.g., POST /cards/{CardID}/cryptogram) are no longer allowed.
        This is typically done when the card is no longer in use, has been removed from the system, or must be de-tokenized for compliance reasons. When deleted, the Network Token is excluded from the card response object and becomes non-functional for payments.
      operationId: delete_network_token_by_card_id
      security:
        - bearerAuth: []
      parameters:
        - name: card_id
          in: path
          required: true
          schema:
            type: string
            title: Card Id
      responses:
        "204":
          description: Network token deleted
        "401": *401error
        "403": *403error
        "404": *404cardError
        "500": *500error
        "503": *503error
  /cards/{card_id}/cryptogram:
    post:
      tags:
        - Network Tokens
      summary: Request cryptogram
      description: Fetch Cryptogram by Card ID
      operationId: fetch-cryptogram
      security:
        - bearerAuth: []
      parameters:
        - name: card_id
          in: path
          required: true
          schema:
            type: string
            title: Card Id
      x-codeSamples:
        - lang: curl
          label: "Normal cryptogram (empty)"
          source: |
            curl -X POST https://sandbox.vgsapi.com/cards/card_123/cryptogram \
              -H "Authorization: Bearer <JWT_TOKEN>" \
              -H "Content-Type: application/vnd.api+json" \
              -d '{
                "data": {
                  "attributes": {}
                }
              }'
        - lang: curl
          label: "Full cryptogram request"
          source: |
            curl -X POST https://sandbox.vgsapi.com/cards/card_123/cryptogram \
              -H "Authorization: Bearer <JWT_TOKEN>" \
              -H "Content-Type: application/vnd.api+json" \
              -d '{
                "data": {
                  "attributes": {
                    "currency_code": "USD",
                    "amount": 100.5,
                    "transaction_type": "ECOM",
                    "cryptogram_type": "TAVV"
                  }
                }
              }'
      requestBody:
        required: false
        content:
          application/vnd.api+json:
            schema:
              $ref: "#/components/schemas/CryptoFetchRequest"
            examples:
              normal:
                summary: Request a cryptogram for a network token by card id (empty)
                description: |
                  Returns card data including cryptogram  for a network token provisioned for the card
                value:
                  data:
                    attributes: {}
              full:
                summary: Request a cryptogram for a network token by card id (complete)
                description: |
                  Returns card data including cryptogram  for a network token provisioned for the card
                value:
                  data:
                    attributes:
                      currency_code: USD
                      amount: 100.5
                      transaction_type: ECOM
                      cryptogram_type: TAVV
      responses:
        "200":
          description: Successful cryptogram fetch response
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/NetworkTokenAndCryptogramResource"
              example:
                data:
                  id: NTK6j75fBx46Lzd3G3aVkfGQF
                  type: network_tokens
                  attributes:
                    bin: "411321"
                    created_at: 2025-01-17T12:53:17.94829
                    cryptogram:
                      eci: "07"
                      type: TAVV
                      value: JWrMYLqNQjmEHQDAZbSx+A==
                    exp_month: 9
                    exp_year: 27
                    last4: "2304"
                    network_token: "4113216317012304"
                    payment_account_reference: V4243058293132582787411225618
                    state: active
                    updated_at: 2025-01-17T12:53:17.948293
                metadata:
                  observability:
                    client_id: ACoKRUTV7-config-ci-5I76w
                    fingerprint: 4GqVMr6PvdWHn5qfb66TquParUHsTiFsjJCFaDpVed8KbAmz4bSftQeNQBb
                    account_id: 37199757-3a4f-418f-bcf4-4119d1dbd39e
                    trace_id: f2046b6548e7dbe5793adee1f4a13c63
                    vault_id: tntipby064g
        "400":
          description: The request was invalid.
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                unsupported-type:
                  summary: Cryptogram type not supported (DTVV not enabled)
                  value:
                    errors:
                      - summary: Failed to fetch cryptogram
                        detail: DTVV is not enabled. Please contact support at support@verygoodsecurity.com to enable DTVV for your account
                        error_code: cryptogram-unsupported-type
                    meta:
                      observability:
                        client_id: ACoKRUTV7-config-ci-5I76w
                        fingerprint: 4GqVMr6PvdWHn5qfb66TquParUHsTiFsjJCFaDpVed8KbAmz4bSftQeNQBb
                        account_id: 37199757-3a4f-418f-bcf4-4119d1dbd39e
                        trace_id: f2046b6548e7dbe5793adee1f4a13c63
                        vault_id: tntipby064g
                invalid-currency:
                  summary: Currency code is not valid (must follow ISO 4217)
                  value:
                    errors:
                      - summary: Failed to fetch cryptogram
                        detail: The provided currency is invalid. Please ensure the currency code follows the standard ISO 4217 format (e.g., USD, EUR).
                        error_code: cryptogram-invalid-currency
                    meta:
                      observability:
                        client_id: ACoKRUTV7-config-ci-5I76w
                        fingerprint: 4GqVMr6PvdWHn5qfb66TquParUHsTiFsjJCFaDpVed8KbAmz4bSftQeNQBb
                        account_id: 37199757-3a4f-418f-bcf4-4119d1dbd39e
                        trace_id: f2046b6548e7dbe5793adee1f4a13c63
                        vault_id: tntipby064g
                invalid-amount:
                  summary: Invalid amount provided for cryptogram generation
                  value:
                    errors:
                      - summary: Failed to fetch cryptogram
                        detail: errorMessage
                        error_code: cryptogram-invalid-amount
                    meta:
                      observability:
                        client_id: ACoKRUTV7-config-ci-5I76w
                        fingerprint: 4GqVMr6PvdWHn5qfb66TquParUHsTiFsjJCFaDpVed8KbAmz4bSftQeNQBb
                        account_id: 37199757-3a4f-418f-bcf4-4119d1dbd39e
                        trace_id: f2046b6548e7dbe5793adee1f4a13c63
                        vault_id: tntipby064g
        "401": *401error
        "403": *403error
        "404": *404cardError
        "422": *422error
        "424":
          description: Network Token Not Provisioned or Not Active
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                fetch-failed:
                  summary: Generic cryptogram fetch failure due to network or external service issues
                  value:
                    errors:
                      - summary: Failed to fetch cryptogram
                        detail: There was a failure in fetching the cryptogram, possibly due to external service issues or network failures
                        error_code: cryptogram-fetch-failed
                    meta:
                      observability:
                        trace_id: d45ced1ebf3fb9cd3cc386e9489d1b42
                        client_id: ACa6ayoHU-am-sa-9-oF1Qj
                        vault_id: tntvhmnsawa
                        account_id: ACTfJPr7umSPZiJJckX3dMYLP
                        fingerprint: 4GqVMr6PvjLWZzJDv3XcojYVTsGCJ7FnciqujuFj8bywV9vRakWy2TCK9tA
                validation-failed:
                  summary: One or more parameters are invalid for cryptogram fetch
                  value:
                    errors:
                      - summary: Failed to fetch cryptogram
                        detail: Invalid parameter
                        error_code: cryptogram-fetch-validation-failed
                    meta:
                      observability:
                        trace_id: d45ced1ebf3fb9cd3cc386e9489d1b42
                        client_id: ACa6ayoHU-am-sa-9-oF1Qj
                        vault_id: tntvhmnsawa
                        account_id: ACTfJPr7umSPZiJJckX3dMYLP
                        fingerprint: 4GqVMr6PvjLWZzJDv3XcojYVTsGCJ7FnciqujuFj8bywV9vRakWy2TCK9tA
                nt-not-found:
                  summary: Network token not found for given parameters
                  value:
                    errors:
                      - summary: Failed to fetch cryptogram
                        detail: Network token not found
                        error_code: network-token-not-found
                    meta:
                      observability:
                        trace_id: d45ced1ebf3fb9cd3cc386e9489d1b42
                        client_id: ACa6ayoHU-am-sa-9-oF1Qj
                        vault_id: tntvhmnsawa
                        account_id: ACTfJPr7umSPZiJJckX3dMYLP
                        fingerprint: 4GqVMr6PvjLWZzJDv3XcojYVTsGCJ7FnciqujuFj8bywV9vRakWy2TCK9tA
                nt-not-active:
                  summary: The network token exists but is no longer active
                  value:
                    errors:
                      - summary: Failed to fetch cryptogram
                        detail: The network token is no longer active
                        error_code: network-token-not-active
                    meta:
                      observability:
                        trace_id: d45ced1ebf3fb9cd3cc386e9489d1b42
                        client_id: ACa6ayoHU-am-sa-9-oF1Qj
                        vault_id: tntvhmnsawa
                        account_id: ACTfJPr7umSPZiJJckX3dMYLP
                        fingerprint: 4GqVMr6PvjLWZzJDv3XcojYVTsGCJ7FnciqujuFj8bywV9vRakWy2TCK9tA
                crypto-not-enabled:
                  summary: Account is not configured to fetch cryptograms
                  value:
                    errors:
                      - summary: Failed to fetch cryptogram
                        detail: Account is not configured to fetch a cryptogram
                        error_code: nt-crypto-fetch-not-enabled
                    meta:
                      observability:
                        trace_id: d45ced1ebf3fb9cd3cc386e9489d1b42
                        client_id: ACa6ayoHU-am-sa-9-oF1Qj
                        vault_id: tntvhmnsawa
                        account_id: ACTfJPr7umSPZiJJckX3dMYLP
                        fingerprint: 4GqVMr6PvjLWZzJDv3XcojYVTsGCJ7FnciqujuFj8bywV9vRakWy2TCK9tA
        "500": *500error
        "503": *503error
webhooks:
  account-updater-webhooks:
    post:
      tags:
        - Account Updater Events
      summary: Account updater events
      operationId: account-updater-webhook
      security:
        - bearerAuth: []
      description: |
        When you enroll cards using the CMP's Create Card API, enrollment in account updater depends on the configured workflow. If the account update workflow is enabled, you'll automatically receive notifications for the card's lifecycle events. Each notification includes the card ID, enabling you to easily retrieve the most up-to-date card information with a simple GET request. If the workflow is not configured for account updater, you will need to explicitly enroll the card by making a request to the /card-updates endpoint. This ensures flexibility for customers to manage enrollment based on their specific needs.

        Once a card is enrolled in Account Updater:
        1. Receive notifications for events like
            i. Card updates
            i. Expirations
            i. Account closures
            i. And others
        2. Signature - Read more about webhook signature to configure authentication properly
        3. Extract the cardID from each notification
        4. Use the cardID to make a GET request to retrieve the updated card data
            i. Get Card - Get information on registered cards

        ## Account Updater Events
        After a card has been enrolled for account updates, there are a few events which may occur to update the status of the card. You may receive these status updates via our Webhook integration. Here is a brief explanation of what each update means:

        | Notification Type | Event Description |
        | ----------------- | ----------------- |
        | cmp_au_card.updated | **Account number change message**: This event is triggered when a cardholder opens a new account with a participating issuer or when a new card is issued. For e.g. this could be due to new account creation, lost or stolen card, or when a card holder gets upgraded to Platinum or downgraded, or, due to a portfolio change (one bank to another). |
        | cmp_au_card.expired | **Expiration date change** This event denotes an expiration date change event. Whenever the card expires but has the same PAN, then, a new expiration date is issued. This event is an indication that the card expired (and so a new date is issued). Typically, cards have an expiration date of 2, 3 or x years (it used to be 5 but we rarely see them these days). Sometimes, an issuer can have an expiration for 1 year (for brand new card holders as they do not have enough credit). |
        | cmp_au_card.closed | **Closed account advice** This event is triggered when the issuer reports the closure of the cardholder's account i.e. cardholder's account associated with the particular card is no longer active/closed providing an important update for merchants to keep their records accurate and avoid attempting transactions with invalid or closed accounts. |
        | cmp_au_card.non_participating | **Non-participating BIN** This event represents a non-participating BIN event, indicating that cards linked to these BINs will not receive updates through the account updater service. i.e. BIN of a particular card is not participating in the account updater service and merchants subscribed to account updater will not receive updates for cards associated with non-participating BINs. |
        | cmp_au_card.contact_cardholder_advice | **Contact cardholder advice** This event indicates the issuer is letting the merchant know that something has changed and the merchant should force the customer to key enter the credential and the update will not be shared via the account updater channel for the merchant. In short the merchant must contact the cardholder for more information or clarification. |
        | cmp_au_card.unknown | **Unknown** is a valid card state returned by networks. It indicates that the card is eligible for automatic updates (participating BIN), but the network was temporarily unable to find a match. The card is still successfully subscribed for account updates. When a card is marked Unknown, the network cannot validate or reject it, and the **guidance is to treat these cards as valid**. Networks periodically recheck these cards, and once an update is available, the status will automatically update from Unknown to the card’s current state (e.g., Enrolled, Expired, or Closed). |
        | cmp_au_card.enrolled | This event is triggered when a card is successfully enrolled in account updater or when the network confirms that the card status remains unchanged. **Successfully enrolled** - The card is successfully enrolled for updates from the networks. **Match made, account number and expiration date unchanged** - This event implies that the card is already enrolled for account updater services, confirming the card's account number and expiration date haven't changed (matched) since the last card update. |
        | cmp_au_card.opt_out | **Cardholder Opt-Out Note** (Stop Advice) is placed on a card |
        | cmp_au_card.enrollment.failed | The card could not be enrolled for account updates with the networks |

        This event is triggered when the cardholder chooses to opt-out of the account updater service i.e. when the cardholder does not want their account information automatically updated through the account updater service. Opting out is typically a deliberate choice made by the cardholder.

        ## Enrollment Failure Reason Codes:

        | Reason Code | Reason Text |
        | ----------- | -----------
        | card-brand-not-supported | **XXX card brand is not supported.** Currently, only Visa and Mastercard cards are supported. This error will be returned if an Amex, Discover, or any other card scheme is used. |
        | declined | **VGS merchant not found** This error typically indicates that the customer has not been onboarded to use the account updater with the provided vault credentials. |
        | internal-server-error | Something went wrong. |

        Note: The 'card_first8' field will be returned in the card notifications only for Visa and Mastercard cards.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CardUpdateWebhook"
            examples:
              card-updated:
                summary: Card Updated
                description: A card enrolled in account updater was updated
                value:
                  description: Card updated
                  details:
                    card_id: CRDecqZp3xRgXU3TFmtcDdzQs
                    card_last4: "5698"
                    card_first8: "12345678"
                    card_bin: "123456"
                    card_fingerprint: gpwktMGS8NtJervwhyZCEmTMfrrQMXX6vaoyrQmRsT6s
                    fingerprint_matches: "[\"CRDnUwLQMbtEwgyYRPT5wfY5k\",\"CRDiXN4YJy97BKTmpQgimqiTr\"]"
                    new_account_number: "************5698"
                    new_expiration_date: "0227"
                    occurred_at: 2024-01-17T00:00Z
                    old_account_number: "************7343"
                    old_expiration_date: "0424"
                    reason_code: A
                    reason_text: The card number was updated.
                  event: cmp_au_card.updated
                  fingerprint: 0734f9289326955d9b323c26b281fd8112f78ef56acd09a3dc2b8c7a9a13c948
                  grouping: every_single
                  id: bba88542-cfb1-42f8-8f63-aba60d62917c
                  integration_id: IN6VgSvLVRV2j2iuxugi4mh7
                  occurrence: 1
                  org_id: AC21kskfJCLyrkVjmAT6gU9X
                  producer:
                    application_name: calm-api
                    application_protocol: http
                  scope: vault
                  summary: |
                    Card "CRDecqZp3xRgXU3TFmtcDdzQs" has been updated within vault tntvlyn1nof
                  tenant: ACT9eeBkBsxXe9wWJkQdpG2kC
                  timestamp: "2024-01-18T23:49:31.809Z"
              card-expired:
                summary: Card Expired
                description: A card enrolled in account updater has expired
                value:
                  description: Card expired
                  details:
                    card_bin: "510026"
                    card_first8: "51002600"
                    card_id: CRDecqZp3xRgXU3TFmtcDdzQs
                    card_last4: "9202"
                    card_fingerprint: gpwktMGS8NtJervwhyZCEmTMfrrQMXX6vaoyrQmRsT6s
                    new_account_number: "************9202"
                    new_expiration_date: "1203"
                    occurred_at: "2024-08-26T23:27:47.040451739Z"
                    old_account_number: "************9202"
                    old_expiration_date: "1299"
                    reason_code: E
                    reason_text: The cards expiration date was updated.
                  event: cmp_au_card.expired
                  fingerprint: 153dd940fc9f22fd493496fcf62c53bb513e41dc99687b7f6e2154be3d84aae2
                  grouping: every_single
                  id: ffaaf4e3-399d-47ef-a643-5b2784511498
                  integration_id: INdNzxhJUz6afZvmKNwY8XRd
                  occurrence: 1
                  org_id: ACj9SFZWEnwhUfi6bm2xRtDb
                  producer:
                    application_name: card-management-platform
                    application_protocol: http
                  scope: vault
                  summary: Card "CRDecqZp3xRgXU3TFmtcDdzQs" has been expired within vault tnt6k1lu5fz
                  tenant: ACT9eeBkBsxXe9wWJkQdpG2kC
                  timestamp: "2024-08-26T23:27:47.041Z"
              card-closed:
                summary: Card Closed
                description: A card enrolled in account updater was closed
                value:
                  description: Card closed
                  details:
                    card_bin: "510026"
                    card_first8: "51002600"
                    card_id: CRDecqZp3xRgXU3TFmtcDdzQs
                    card_last4: "9203"
                    card_fingerprint: gpwktMGS8NtJervwhyZCEmTMfrrQMXX6vaoyrQmRsT6s
                    occurred_at: "2024-08-26T23:39:40.292979968Z"
                    old_account_number: "************9203"
                    old_expiration_date: "1299"
                    reason_code: C
                    reason_text: The card was closed.
                  event: cmp_au_card.closed
                  fingerprint: 0f2adcc48c37aab4d13aa191e4d32739c62e9448e71de194c6403cfbde3faf25
                  grouping: every_single
                  id: fe9c2013-3af1-446a-b82f-57820cf06039
                  integration_id: INdNzxhJUz6afZvmKNwY8XRd
                  occurrence: 1
                  org_id: ACj9SFZWEnwhUfi6bm2xRtDb
                  producer:
                    application_name: card-management-platform
                    application_protocol: http
                  scope: vault
                  summary: Card "CRDecqZp3xRgXU3TFmtcDdzQs" has been closed within vault tnt6k1lu5fz
                  tenant: ACT9eeBkBsxXe9wWJkQdpG2kC
                  timestamp: "2024-08-26T23:39:40.293Z"
              card-cardholder-advice:
                summary: Contact Cardholder
                description: |
                  A card enrolled in account updater is in a status that requires the customer update their payment information with you.
                value:
                  description: Card Contact Cardholder Advice
                  details:
                    card_bin: "400021"
                    card_first8: "40002100"
                    card_id: CRDecqZp3xRgXU3TFmtcDdzQs
                    card_last4: "9203"
                    card_fingerprint: gpwktMGS8NtJervwhyZCEmTMfrrQMXX6vaoyrQmRsT6s
                    occurred_at: "2024-08-26T23:42:04.359764910Z"
                    old_account_number: "************9203"
                    old_expiration_date: "1299"
                    reason_code: Q
                    reason_text: Contact the cardholder.
                  event: cmp_au_card.contact_cardholder_advice
                  fingerprint: 6f34dccef156c37b21e498e034aa54ead9c3a7943e8927f5241cc0d9aa8b8245
                  grouping: every_single
                  id: 8d522161-be8c-4f73-aea3-c131f6c8c94f
                  integration_id: INdNzxhJUz6afZvmKNwY8XRd
                  occurrence: 1
                  org_id: ACj9SFZWEnwhUfi6bm2xRtDb
                  producer:
                    application_name: card-management-platform
                    application_protocol: http
                  scope: vault
                  summary: Card "CRDecqZp3xRgXU3TFmtcDdzQs" has opted out and the merchant needs to contact cardholder for tenant tnt6k1lu5fz
                  tenant: ACT9eeBkBsxXe9wWJkQdpG2kC
                  timestamp: "2024-08-26T23:42:04.360Z"
              card-nonparticipating:
                summary: Card Non-Participating
                description: |
                  A card enrolled in account updater is not, or is no longer, participating in account updater and no updates for this card will be received.
                value:
                  description: Card Non-Participating
                  details:
                    card_id: CRDecqZp3xRgXU3TFmtcDdzQs
                    card_fingerprint: gpwktMGS8NtJervwhyZCEmTMfrrQMXX6vaoyrQmRsT6s
                    occurred_at: "2024-08-26T23:40:19.234066706Z"
                    reason_code: N
                    reason_text: Non-participating BIN.
                  event: cmp_au_card.non_participating
                  fingerprint: d7dd52da0a4e6654ac5b6564c9d4b7d9069e050d4ce073d701950eea537a8253
                  grouping: every_single
                  id: 8f4bceaa-6276-4af7-aa60-ca54cea5ad59
                  integration_id: INdNzxhJUz6afZvmKNwY8XRd
                  occurrence: 1
                  org_id: ACj9SFZWEnwhUfi6bm2xRtDb
                  producer:
                    application_name: card-management-platform
                    application_protocol: http
                  scope: vault
                  summary: Card "CRDecqZp3xRgXU3TFmtcDdzQs" is not participating for tenant tnt6k1lu5fz
                  tenant: ACT9eeBkBsxXe9wWJkQdpG2kC
                  timestamp: "2024-08-26T23:40:19.234Z"
              card-unknown:
                summary: Valid
                description: |
                  A card enrolled in account updater is valid, and there are no updates to process.
                value:
                  description: Card Valid
                  details:
                    card_id: CRDecqZp3xRgXU3TFmtcDdzQs
                    card_fingerprint: gpwktMGS8NtJervwhyZCEmTMfrrQMXX6vaoyrQmRsT6s
                    occurred_at: "2024-08-26T23:41:07.388739782Z"
                    reason_code: U
                    reason_text: Unknown value received on the card from networks.
                  event: cmp_au_card.unknown
                  fingerprint: 2fb22ef0e6628e048abc725364cc3122eb242f62d75c3628603ffdf86247ca01
                  grouping: every_single
                  id: 921a0a92-7b88-45f4-8454-11a3492e2d85
                  integration_id: INdNzxhJUz6afZvmKNwY8XRd
                  occurrence: 1
                  org_id: ACj9SFZWEnwhUfi6bm2xRtDb
                  producer:
                    application_name: card-management-platform
                    application_protocol: http
                  scope: vault
                  summary: Card "CRDecqZp3xRgXU3TFmtcDdzQs" is valid for tenant tnt6k1lu5fz
                  tenant: ACT9eeBkBsxXe9wWJkQdpG2kC
                  timestamp: "2024-08-26T23:41:07.389Z"
              card-enrolled:
                summary: Card Enrolled
                description: |
                  A card enrolled in account updater has finished the enrollment process.
                value:
                  description: Card Enrolled
                  details:
                    card_id: CRDecqZp3xRgXU3TFmtcDdzQs
                    card_fingerprint: gpwktMGS8NtJervwhyZCEmTMfrrQMXX6vaoyrQmRsT6s
                    occurred_at: "2024-08-26T23:37:49.990037306Z"
                    reason_code: V
                    reason_text: The card is enrolled successfully, or card data is unchanged.
                  event: cmp_au_card.enrolled
                  fingerprint: 86be4a9f802b5de79c4106034ea4b9454222e31102a36a9979622406360304cd
                  grouping: every_single
                  id: e376d3b5-d1ba-4c47-9ea0-ba4f72d66074
                  integration_id: INdNzxhJUz6afZvmKNwY8XRd
                  occurrence: 1
                  org_id: ACj9SFZWEnwhUfi6bm2xRtDb
                  producer:
                    application_name: card-management-platform
                    application_protocol: http
                  scope: vault
                  summary: Card "CRDecqZp3xRgXU3TFmtcDdzQs" enrolled for tenant tnt6k1lu5fz
                  tenant: ACT9eeBkBsxXe9wWJkQdpG2kC
                  timestamp: "2024-08-26T23:37:49.990Z"
              card-optout:
                summary: Card Opted-Out
                description: |
                  A card enrolled in account updater has been opted-out of account updater, and no updates will be received for this card.
                value:
                  description: Card Opt Out
                  details:
                    card_id: CRDecqZp3xRgXU3TFmtcDdzQs
                    card_fingerprint: gpwktMGS8NtJervwhyZCEmTMfrrQMXX6vaoyrQmRsT6s
                    occurred_at: "2024-08-26T23:43:20.557443407Z"
                    reason_code: O
                    reason_text: The card is opted out from account updates.
                  event: cmp_au_card.opt_out
                  fingerprint: 9b7db17447fd95df6ef6d56eedd703f0fa1f44a1051362fdcc440b20aec119c5
                  grouping: every_single
                  id: 059b80a9-eea8-4a96-bbb4-6e40bc5e980b
                  integration_id: INdNzxhJUz6afZvmKNwY8XRd
                  occurrence: 1
                  org_id: ACj9SFZWEnwhUfi6bm2xRtDb
                  producer:
                    application_name: card-management-platform
                    application_protocol: http
                  scope: vault
                  summary: Card "CRDecqZp3xRgXU3TFmtcDdzQs" has opted out for tenant tnt6k1lu5fz
                  tenant: ACT9eeBkBsxXe9wWJkQdpG2kC
                  timestamp: "2024-08-26T23:43:20.557Z"
              enrollment-failed:
                summary: Enrollment failed
                description: An attempt to enroll a card in account updater failed.
                value:
                  description: Card Enrollment Failed
                  details:
                    card_id: CRDecqZp3xRgXU3TFmtcDdzQs
                    occurred_at: "2024-08-26T23:38:30.888437573Z"
                    reason_code: card-brand-not-supported
                    reason_text: XXX card brand is not supported
                  event: cmp_au_card.enrollment.failed
                  fingerprint: 829d779c3b0e18b9525447dd83650003c2754386846a396b84971bfa4d9e08db
                  grouping: every_single
                  id: eeb80afd-8efa-48b9-8ada-1ebac2565716
                  integration_id: INdNzxhJUz6afZvmKNwY8XRd
                  occurrence: 1
                  org_id: ACj9SFZWEnwhUfi6bm2xRtDb
                  producer:
                    application_name: card-management-platform
                    application_protocol: http
                  scope: vault
                  summary: Card "CRDecqZp3xRgXU3TFmtcDdzQs" enrollment failed for tenant tnt6k1lu5fz
                  tenant: ACT9eeBkBsxXe9wWJkQdpG2kC
                  timestamp: "2024-08-26T23:38:30.888Z"
        required: true
      responses:
        "200":
          description: |
            Return a 200 status to indicate that the data was received successfully.
  network-tokens-webhooks:
    post:
      tags:
        - Network Token Events
      summary: Network token events
      operationId: network-tokens-webhook
      security:
        - bearerAuth: []
      description: |
        After a Network Token has been enrolled, there are a few key events that may occur. These fall into two broad categories:
        - Lifecycle Events: These represent billable actions that typically result in a change to the card metadata or indicate successful provisioning.
        - Status Updates: These reflect changes to the token's status (e.g., suspended or deleted) and are not billable.
        You may receive these events via our Webhook integration or view them in the Usage Reports section of your organization's Dashboard.
        Below is an explanation of each:

        | Network Token Status | VGS Network Token State  | VGS Reason Code                       | Description                                                                             | Classification Type    |
        |----------------------|--------------------------|---------------------------------------|-----------------------------------------------------------------------------------------|------------------------|
        | Updated              | card_updated             | cmp_card_updated                      | The network has updated the card metadata.                                              | Lifecycle Event        |
        | Suspended            | suspended                | cmp_network_token.suspended           | A network token has been suspended by the issuing card network (Mastercard, Visa, etc). | Status Update          |
        | Activated            | activated                | cmp_network_token.activated           | A network token has been activated following a suspension.                              | Status Update          |
        | Deleted              | deleted                  | cmp_network_token.deleted             | A network token has been deleted via the API.                                           | Status Update          |
        | Provisioned          | active                   | cmp_network_token.provisioned         | A network token has been provisioned.                                                   | Provisioning           |
        | Failed               | failed                   | cmp_network_token.provisioning_failed | The network token was not provisioned (provisioning failed).                            | Failed Provisioning    |

        ### Network Token Expiration

        - There is **no** network token expiration event notification from card networks. Instead, networks automatically renew the network token expiration date when applicable.
        - Network Token expiration is managed by card networks and is independent of the PAN expiration.
        - **Visa:** Network Token expiration typically matches the PAN expiration.
        - **Mastercard:** Network Tokens generally expire 36 months after provisioning, meaning they may remain active even if the PAN has expired.
        - Network Tokens do not automatically re-provision upon expiration.
        - Transactions will fail if either the network token or PAN is expired.
        - When a network token expires, you can check for network token updates via account updater using the cardID OR subscribe cards for account updater with VGS to automatically receive card updates.

        **Key Actions:**
        - Monitor both PAN and network token expiration dates.
        - Implement logic to handle transaction failures due to expiration.
        - Use account updater to keep card details up to date.

        ### Network Token Deletion
        - Network Tokens remain active unless explicitly deleted by the issuer.
        - The cmp_network_token.deleted event indicates that an network token has been removed.
        - Currently, merchants cannot delete network tokenss via the Card Management Platform (CMP), but this functionality will be introduced soon.

        Provisioning Failure Reason Codes:

        | Reason Code            | Reason Text                                                                                                  | Customer Retry | VGS Retry |
        |------------------------|--------------------------------------------------------------------------------------------------------------|---------------|-----------|
        | provisioning_failed    | Invalid payment instrument or data associated with the payment instrument                                    | Yes           | No        |
        | card_not_allowed       | Card cannot be used for tokenization at this moment. Please try again later                                  | Yes           | No        |
        | card_not_allowed       | The requested action is not allowed for a given PAN. This card is valid but cannot be used for tokenization. | No            | No        |
        | declined               | This card is not eligible for tokenization at this moment with the Network; Retry at a later time.           | Yes           | No        |
        | declined               | No further operations are allowed. Contact bank                                                              | No            | No        |
        | service_unavailable    | Downstream service unavailable; retry later                                                                  | No            | Yes       |
        | rejected               | This card is not eligible for tokenization at this moment with the Network; Retry later.                     | Yes           | No        |

        CMP includes these reason codes and texts from the network in both the API response and the webhook notifications.

        Retries
        - **Customer Retries** (Yes): If this column is marked "Yes", the customer can resend the network token provisioning request using the cardID and the dedicated network token endpoint.
        - When Duplicate Card Detection is enabled, resending the same card object via POST will return a 303 (no new cardID). Customers must use the existing cardID with the dedicated network token endpoint.
          - When Duplicate Card Detection is disabled, resending the same card object via POST will generate a new cardID.
            - In onCreate enrollment type/mode, CMP will retry provisioning automatically for the new cardID.
            - In manual enrollment type/mode, the customer must resend the request using the new cardID.
          - Find more information on Duplicate Card Detection [here](https://docs.verygoodsecurity.com/card-management/account-management/cards#duplicate-card-detection).
        - **VGS Retries** (Yes): If this column is marked "Yes", VGS will automatically retry network token provisioning up to 3 times within a 12-hour window. If all three attempts fail, VGS will stop retrying, and no customer notification will be sent.

        CMP aggregates all network token notifications into the **cmp_network_token.updated** event. Unlike account updater, which emits distinct event types for each notification, network token events share a common structure. The **state** field denotes the specific notification type, and the **event** field remains **cmp_network_token.updated**.
        - Lifecycle events: card_updated
        - Status updates: suspended, activated, deleted

        Note: The 'card_first8' field will be returned in the card notifications only for Visa and Mastercard cards.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CardUpdateWebhook"
            examples:
              network-token-updated:
                summary: Token updated
                value:
                  description: Network token updated
                  details:
                    card_id: CRDNDuSxRXmWMdGkxaaPB8Q7ZVZnQTXJnebcjFD9T9DyK5EiP2No
                    card_bin: "545503"
                    card_expiration_month: "4"
                    card_expiration_year: "2023"
                    card_last4: "6828"
                    card_first8: "54550378"
                    payment_account_reference: V0013545834930585516258022674
                    created_at: "2024-08-28T23:11:00.013532771Z"
                    network_token_expiration_month: "2"
                    network_token_expiration_year: "2023"
                    network_token_id: NTKu5rM55z4PNMLW9Rqrhd466
                    network_token_bin: "123456"
                    network_token_last4: "1234"
                    state: card_updated
                    tenant_id: ACT9eeBkBsxXe9wWJkQdpG2kC
                    updated_at: "2024-08-28T23:11:00.013532771Z"
                    reason_code: cmp_card_updated
                    reason_text: The network has updated the card metadata.
                  event: cmp_network_token.updated
                  fingerprint: f438b385c1ed2c40a9379fcea75b3a40eec865fa3c9d0812ab212d45e5a84eca
                  grouping: every_single
                  id: 7a4a31dd-8494-4400-8c19-0e88b814089c
                  integration_id: INvwsS1BGFs6ZjQ2eCiv9JV1
                  occurrence: 1
                  org_id: ACmAx8rXF16qPupyWzyLM6v9
                  producer:
                    application_name: calm-api
                    application_protocol: http
                  scope: vault
                  summary: |
                    A Network Token for card id 'CRDNDuSxRXmWMdGkxaaPB8Q7ZVZnQTXJnebcjFD9T9DyK5EiP2No' has been updated
                  tenant: ACT9eeBkBsxXe9wWJkQdpG2kC
                  timestamp: "2024-07-18T06:23:48.711Z"
              network-token-suspended:
                summary: Token suspended
                value:
                  description: Network token suspended
                  details:
                    card_id: CRDNDuSxRXmWMdGkxaaPB8Q7ZVZnQTXJnebcjFD9T9DyK5EiP2No
                    card_bin: "545503"
                    card_expiration_month: "4"
                    card_expiration_year: "2023"
                    card_last4: "6828"
                    card_first8: "54550378"
                    payment_account_reference: V0013545834930585516258022674
                    created_at: "2024-08-28T23:11:00.013532771Z"
                    network_token_expiration_month: "2"
                    network_token_expiration_year: "2023"
                    network_token_id: NTKu5rM55z4PNMLW9Rqrhd466
                    network_token_bin: "123456"
                    network_token_last4: "1234"
                    state: suspended
                    tenant_id: ACT9eeBkBsxXe9wWJkQdpG2kC
                    updated_at: "2024-08-28T23:11:00.013532771Z"
                    reason_code: cmp_network_token.suspended
                    reason_text: A network token has been suspended by the issuing card network.
                  event: cmp_network_token.updated
                  fingerprint: f438b385c1ed2c40a9379fcea75b3a40eec865fa3c9d0812ab212d45e5a84eca
                  grouping: every_single
                  id: 7a4a31dd-8494-4400-8c19-0e88b814089c
                  integration_id: INvwsS1BGFs6ZjQ2eCiv9JV1
                  occurrence: 1
                  org_id: ACmAx8rXF16qPupyWzyLM6v9
                  producer:
                    application_name: calm-api
                    application_protocol: http
                  scope: vault
                  summary: |
                    A Network Token for card id 'CRDNDuSxRXmWMdGkxaaPB8Q7ZVZnQTXJnebcjFD9T9DyK5EiP2No' has been suspended
                  tenant: ACT9eeBkBsxXe9wWJkQdpG2kC
                  timestamp: "2024-07-18T06:23:48.711Z"
              network-token-activated:
                summary: Token activated
                value:
                  description: Network token activated
                  details:
                    card_id: CRDNDuSxRXmWMdGkxaaPB8Q7ZVZnQTXJnebcjFD9T9DyK5EiP2No
                    card_bin: "545503"
                    card_expiration_month: "4"
                    card_expiration_year: "2023"
                    card_last4: "6828"
                    card_first8: "54550378"
                    payment_account_reference: V0013545834930585516258022674
                    created_at: "2024-08-28T23:11:00.013532771Z"
                    network_token_expiration_month: "2"
                    network_token_expiration_year: "2023"
                    network_token_id: NTKu5rM55z4PNMLW9Rqrhd466
                    network_token_bin: "123456"
                    network_token_last4: "1234"
                    state: activated
                    tenant_id: ACT9eeBkBsxXe9wWJkQdpG2kC
                    updated_at: "2024-08-28T23:11:00.013532771Z"
                    reason_code: cmp_network_token.activated
                    reason_text: A network token has been activated.
                  event: cmp_network_token.updated
                  fingerprint: f438b385c1ed2c40a9379fcea75b3a40eec865fa3c9d0812ab212d45e5a84eca
                  grouping: every_single
                  id: 7a4a31dd-8494-4400-8c19-0e88b814089c
                  integration_id: INvwsS1BGFs6ZjQ2eCiv9JV1
                  occurrence: 1
                  org_id: ACmAx8rXF16qPupyWzyLM6v9
                  producer:
                    application_name: calm-api
                    application_protocol: http
                  scope: vault
                  summary: |
                    A Network Token for card id 'CRDNDuSxRXmWMdGkxaaPB8Q7ZVZnQTXJnebcjFD9T9DyK5EiP2No' has been activated
                  tenant: ACT9eeBkBsxXe9wWJkQdpG2kC
                  timestamp: "2024-07-18T06:23:48.711Z"
              network-token-deleted:
                summary: Token deleted
                value:
                  description: Network token deleted
                  details:
                    card_id: CRDNDuSxRXmWMdGkxaaPB8Q7ZVZnQTXJnebcjFD9T9DyK5EiP2No
                    card_bin: "545503"
                    card_expiration_month: "4"
                    card_expiration_year: "2023"
                    card_last4: "6828"
                    card_first8: "54550378"
                    payment_account_reference: V0013545834930585516258022674
                    created_at: "2024-08-28T23:11:00.013532771Z"
                    network_token_expiration_month: "2"
                    network_token_expiration_year: "2023"
                    network_token_id: NTKu5rM55z4PNMLW9Rqrhd466
                    network_token_bin: "123456"
                    network_token_last4: "1234"
                    state: deleted
                    tenant_id: ACT9eeBkBsxXe9wWJkQdpG2kC
                    updated_at: "2024-08-28T23:11:00.013532771Z"
                    reason_code: cmp_network_token.deleted
                    reason_text: A network token has been deleted.
                  event: cmp_network_token.updated
                  fingerprint: f438b385c1ed2c40a9379fcea75b3a40eec865fa3c9d0812ab212d45e5a84eca
                  grouping: every_single
                  id: 7a4a31dd-8494-4400-8c19-0e88b814089c
                  integration_id: INvwsS1BGFs6ZjQ2eCiv9JV1
                  occurrence: 1
                  org_id: ACmAx8rXF16qPupyWzyLM6v9
                  producer:
                    application_name: calm-api
                    application_protocol: http
                  scope: vault
                  summary: |
                    A Network Token for card id 'CRDNDuSxRXmWMdGkxaaPB8Q7ZVZnQTXJnebcjFD9T9DyK5EiP2No' has been deleted.
                  tenant: ACT9eeBkBsxXe9wWJkQdpG2kC
                  timestamp: "2024-07-18T06:23:48.711Z"
              network-token-failed:
                summary: Token provisioning failed
                value:
                  description: Network token provisioning failed
                  details:
                    card_id: CRDNDuSxRXmWMdGkxaaPB8Q7ZVZnQTXJnebcjFD9T9DyK5EiP2No
                    card_bin: "545503"
                    card_expiration_month: "4"
                    card_expiration_year: "2023"
                    card_last4: "6828"
                    card_first8: "54550378"
                    payment_account_reference: ""
                    created_at: "2024-08-28T23:11:00.013532771Z"
                    network_token_expiration_month: ""
                    network_token_expiration_year: ""
                    network_token_bin: ""
                    network_token_id: ""
                    network_token_last4: ""
                    state: failed
                    tenant_id: ACT9eeBkBsxXe9wWJkQdpG2kC
                    updated_at: "2024-08-28T23:11:00.013532771Z"
                    reason_code: cmp_network_token.provisioning_failed
                    reason_text: Invalid payment instrument or data associated with the payment instrument
                  event: cmp_network_token.updated
                  fingerprint: f438b385c1ed2c40a9379fcea75b3a40eec865fa3c9d0812ab212d45e5a84eca
                  grouping: every_single
                  id: 7a4a31dd-8494-4400-8c19-0e88b814089c
                  integration_id: INvwsS1BGFs6ZjQ2eCiv9JV1
                  occurrence: 1
                  org_id: ACmAx8rXF16qPupyWzyLM6v9
                  producer:
                    application_name: calm-api
                    application_protocol: http
                  scope: vault
                  summary: |
                    A Network Token for card id 'CRDNDuSxRXmWMdGkxaaPB8Q7ZVZnQTXJnebcjFD9T9DyK5EiP2No' has been provisioned.
                  tenant: ACT9eeBkBsxXe9wWJkQdpG2kC
                  timestamp: "2024-07-18T06:23:48.711Z"
              network-token-provisioning-succeeded:
                summary: Token provisioning succeeded
                value:
                  description: Network token provisioned
                  details:
                    card_id: CRDNDuSxRXmWMdGkxaaPB8Q7ZVZnQTXJnebcjFD9T9DyK5EiP2No
                    card_bin: "545503"
                    card_expiration_month: "4"
                    card_expiration_year: "2023"
                    card_last4: "6828"
                    card_first8: "54550378"
                    payment_account_reference: V0013545834930585516258022674
                    created_at: "2024-08-28T23:11:00.013532771Z"
                    network_token_expiration_month: "2"
                    network_token_expiration_year: "2023"
                    network_token_id: NTKu5rM55z4PNMLW9Rqrhd466
                    network_token_last4: "1234"
                    state: active
                    tenant_id: ACT9eeBkBsxXe9wWJkQdpG2kC
                    updated_at: "2024-08-28T23:11:00.013532771Z"
                    reason_code: cmp_network_token.provisioned
                    reason_text: A network token has been successfully provisioned.
                  event: cmp_network_token.updated
                  fingerprint: f438b385c1ed2c40a9379fcea75b3a40eec865fa3c9d0812ab212d45e5a84eca
                  grouping: every_single
                  id: 7a4a31dd-8494-4400-8c19-0e88b814089c
                  integration_id: INvwsS1BGFs6ZjQ2eCiv9JV1
                  occurrence: 1
                  org_id: ACmAx8rXF16qPupyWzyLM6v9
                  producer:
                    application_name: calm-api
                    application_protocol: http
                  scope: vault
                  summary: |
                    A Network Token for card id 'CRDNDuSxRXmWMdGkxaaPB8Q7ZVZnQTXJnebcjFD9T9DyK5EiP2No' has failed provisioning.
                  tenant: ACT9eeBkBsxXe9wWJkQdpG2kC
                  timestamp: "2024-07-18T06:23:48.711Z"
        required: true
      responses:
        "200":
          description: |
            Return a 200 status to indicate that the data was received successfully.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.verygoodsecurity.com/auth/realms/vgs/protocol/openid-connect/token
          scopes:
            cards:write: Grants write access to cards
            cards:read: Grants read access to cards
            configurations:read: Grants read access to configurations
            configurations:write: Grants write access to configurations
  schemas:
    AccountProperties:
      type: object
      required:
        - id
        - attributes
        - type
        - relationships
      properties:
        id:
          type: string
          example: ACToasd0asd
        type:
          enum:
            - account
          type: string
          example: account
        attributes:
          type: object
          required:
            - name
          properties:
            name:
              type: string
              example: Bob's Donuts
            created_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
            state:
              type: string
              enum:
                - CREATING
                - CREATED
                - DELETED
        relationships:
          type: object
          required: []
          properties:
            vault:
              $ref: "#/components/schemas/RelatedResource"
            organization:
              $ref: "#/components/schemas/RelatedResource"
            merchant:
              $ref: "#/components/schemas/RelatedResource"
      description: A simplified representation of a Account, typically used in list views.
    AccountUpdateRequest:
      type: object
      required:
        - data
      properties:
        data:
          $ref: "#/components/schemas/AccountUpdate"
    AccountUpdate:
      type: object
      required:
        - attributes
      properties:
        attributes:
          type: object
          required:
            - name
          properties:
            name:
              type: string
              example: Bob's Donuts
    AccountCreate:
      type: object
      required:
        - attributes
        - type
        - relationships
      properties:
        type:
          type: string
          example: account
        attributes:
          type: object
          required:
            - name
          properties:
            name:
              type: string
              example: Bob's Donuts
        relationships:
          type: object
          required:
            - vault
            - organization
          properties:
            vault:
              $ref: "#/components/schemas/RelatedResource"
              example:
                data:
                  id: tntassdsd
                  type: vault
              description: The Vault ID to associate with the account.
            organization:
              $ref: "#/components/schemas/RelatedResource"
              example:
                data:
                  id: ACadasd9ads
                  type: organization
              description: The organization associated with the account.
            merchant:
              $ref: "#/components/schemas/RelatedResource"
              example:
                data:
                  id: MCadasd9ads
                  type: merchant
              description: The merchant associated with the account.
      description: Data transfer object for creating a new Account.
    ConfigurationResource:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - attributes
            - id
            - type
          properties:
            id:
              type: string
              example: nt.visa.enrollment-type
            type:
              enum:
                - configuration
              type: string
            attributes:
              allOf:
                - $ref: "#/components/schemas/BaseConfiguration"
                - type: object
                  required:
                    - state
                  properties:
                    state:
                      type: string
                      enum:
                        - CREATED
                        - ERROR
                        - DELETED
                    created_at:
                      type: string
                      format: date-time
                    updated_at:
                      type: string
                      format: date-time
    ConfigurationPayload:
      allOf:
        - $ref: "#/components/schemas/BaseConfiguration"
      type: object
    # Configuration value types
    ConfigurationValue:
      type: object
      required:
        - value
      properties:
        value:
          type: string
          description: The value of the configuration
          example: on:card.created
    # Add NetworkTokenIdsValue type
    NetworkTokenIdsValue:
      type: object
      properties:
        default:
          type: object
          properties:
            mid:
              type: integer
              description: Merchant ID for network token configuration
              example: 1234567890
    # Configuration request attributes with discriminator
    ConfigurationRequestAttributes:
      allOf:
        - $ref: "#/components/schemas/BaseConfiguration"
    ConfigurationListResponse:
      type: object
      required:
        - data
        - jsonapi
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/ConfigurationResourceData"
        jsonapi:
          $ref: "#/components/schemas/JsonApiVersion"
        metadata:
          $ref: "#/components/schemas/MetadataResponse"
    ConfigurationResourceData:
      type: object
      required:
        - id
        - type
        - attributes
      properties:
        id:
          type: string
          example: ABCgHe5SvbeHasdeGclc
        type:
          type: string
          example: configurations
        attributes:
          $ref: "#/components/schemas/ConfigurationAttributes"
    ConfigurationAttributes:
      type: object
      required:
        - key
        - value
        - state
        - created_at
        - updated_at
      properties:
        key:
          type: string
          example: nt.visa.enrollment-type
        state:
          enum:
            - CREATED
            - ERROR
            - DELETED
          type: string
        value:
          type: string
          example: on:card.created
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    # Add missing WorkflowValue and WorkflowConfig
    WorkflowValue:
      type: string
      enum:
        - on:card.created
        - none
      description: Configuration value for workflow settings
    WorkflowConfig:
      type: object
      required:
        - key
        - value
      properties:
        key:
          type: string
          enum:
            - nt.visa.workflow
            - au.visa.workflow
            - nt.mastercard.workflow
            - nt.discover.workflow
            - nt.amex.workflow
            - au.mastercard.workflow
            - au.discover.workflow
            - au.amex.workflow
        value:
          $ref: "#/components/schemas/WorkflowValue"
    # Common value types
    EnabledDisabledValue:
      type: string
      enum:
        - enabled
        - disabled
      description: Configuration value for state settings that can be enabled or disabled
    EnrollmentTypeValue:
      type: string
      enum:
        - none
        - manual
        - on-create
      description: Configuration value for enrollment type settings
    # Individual configuration types for validation
    NTVisaStateConfig:
      type: object
      required:
        - key
        - value
      properties:
        key:
          type: string
          enum:
            - nt.visa.state
        value:
          $ref: "#/components/schemas/EnabledDisabledValue"
    NTVisaPARStateConfig:
      type: object
      required:
        - key
        - value
      properties:
        key:
          type: string
          enum:
            - nt.visa.par.state
        value:
          $ref: "#/components/schemas/EnabledDisabledValue"
    NTVisaCryptogramStateConfig:
      type: object
      required:
        - key
        - value
      properties:
        key:
          type: string
          enum:
            - nt.visa.cryptogram.state
        value:
          $ref: "#/components/schemas/EnabledDisabledValue"
    NTVisaCardArtStateConfig:
      type: object
      required:
        - key
        - value
      properties:
        key:
          type: string
          enum:
            - nt.visa.card-art.state
        value:
          $ref: "#/components/schemas/EnabledDisabledValue"
    NTVisaEnrollmentTypeConfig:
      type: object
      required:
        - key
        - value
      properties:
        key:
          type: string
          enum:
            - nt.visa.enrollment-type
        value:
          $ref: "#/components/schemas/EnrollmentTypeValue"
    AUVisaStateConfig:
      type: object
      required:
        - key
        - value
      properties:
        key:
          type: string
          enum:
            - au.visa.state
        value:
          $ref: "#/components/schemas/EnabledDisabledValue"
    AUVisaEnrollmentTypeConfig:
      type: object
      required:
        - key
        - value
      properties:
        key:
          type: string
          enum:
            - au.visa.enrollment-type
        value:
          $ref: "#/components/schemas/EnrollmentTypeValue"
    # Add ConfigurationNTIdsPayload here with the other configuration types
    ConfigurationNTIdsPayload:
      type: object
      required:
        - key
        - value
      properties:
        key:
          type: string
          enum:
            - nt.visa.ids
            - au.visa.ids
        value:
          $ref: "#/components/schemas/NetworkTokenIdsValue"
    # Base configuration type that both request and payload will extend
    BaseConfiguration:
      type: object
      required:
        - key
        - value
      properties:
        key:
          type: string
          description: Configuration key
          example: nt.visa.enrollment-type
        value:
          type: string
          description: Configuration value
          example: on:card.created
    RelatedResource:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - type
            - id
          properties:
            id:
              type: string
            type:
              enum:
                - organization
                - vault
                - merchant
              type: string
        links:
          type: object
          required:
            - href
          properties:
            href:
              type: string
      description: Related resource object.
    AccountResponseMetadata:
      type: object
      required:
        - observability
      properties:
        observability:
          type: object
          required:
            - trace_id
          properties:
            vault_id:
              type: string
              example: tnthasd9ads
              description: The vault id used for this request
            trace_id:
              type: string
              example: 234a5bcd543ef3fa53ce929d0e0e4736
              description: A unique identifier for a request or transaction that's used to trace and monitor its progress. Please provide this value if contacting VGS about a specific request.
            client_id:
              type: string
              example: AC2IS93AW-PAYACC-fullperm-sd8sa
              description: The id of the credential used for this request.
            fingerprint:
              type: string
              example: 4GqVMr6PvhQcBH2Xp7PaDSZadaTUBn7uTjau7hozGhvjGiLgYYC6cNYJF55
      description: Metadata for the response.
    AccountCreationRequest:
      type: object
      required:
        - data
      properties:
        data:
          $ref: "#/components/schemas/AccountCreate"
      description: ""
    RetrieveAccountResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/AccountProperties"
        meta:
          $ref: "#/components/schemas/AccountResponseMetadata"
      description: A response schema representing a single account, including account details and metadata.
    RetrieveAccountListResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/AccountProperties"
        meta:
          $ref: "#/components/schemas/AccountResponseMetadata"
      description: A response schema representing a list of accounts, including account details and metadata.
    CryptoFetchRequest:
      type: object
      properties:
        data:
          type: object
          description: The crypto fetch information.
          properties:
            attributes:
              $ref: "#/components/schemas/CryptoFetchAttributes"
          required:
            - attributes
      additionalProperties: false
      required:
        - data
    CryptogramAttributes:
      type: object
      properties:
        type:
          type: string
          enum:
            - TAVV
            - DTVV
          description: &cryptogramTypeRef |
            Cryptogram type (defaults to TAVV)

            TAVV (Token Authentication Verification Value) and DTVV (Dynamic Token Verification Value) are cryptograms used to authenticate transactions and prevent fraud.

            Customers can initiate transactions using VGS Network Tokens by generating a unique cryptogram.

            * TAVV: This cryptogram is specific to the network token and can be up to 32 characters long. When submitting transactions, networks may require merchants to specify the transaction type explicitly during cryptogram generation.
            * DTVV: Unlike TAVV, DTVV is a 3-characters long cryptogram that is currently supported only for Visa Network Tokens which can increase compatibility with some PSPs. To use DTVV, VGS must be enabled on a case-by-case basis. Merchants interested in enabling DTVV can reach out to support@verygoodsecurity.com for assistance.

            To avoid declines, merchants and acquirers must ensure that:
            - TAVV and DTVV are new and unique for each authorization request
            - TAVV and DTVV are one-time use and not stored beyond the authorization request
            - The TAVV, DTVV, and electronic commerce indicator values provided by the token requester are unchanged when submitted for an authorization request
        value:
          type: string
        eci:
          type: string
          description: |
            An Electronic Commerce Indicator (ECI) is a code that indicates the type of electronic transaction and the result of authentication for a payment.
    JsonApiVersion:
      properties:
        version:
          anyOf:
            - type: number
            - type: "null"
          title: Version
          default: 1.1
        ext:
          anyOf:
            - items:
                type: string
                minLength: 1
                format: uri
              type: array
            - type: "null"
              title: Ext
        profile:
          anyOf:
            - items:
                type: string
                minLength: 1
                format: uri
              type: array
            - type: "null"
              title: Profile
        meta:
          type: object
          title: Meta
      title: JsonApi
    CryptoFetchAttributes:
      type: object
      properties:
        currency_code:
          maxLength: 3
          type: string
          description: ISO 4217 alpha 3 currency code for the transaction
          default: USD
          example: USD
        amount:
          type: number
          multipleOf: 0.01
          format: double
          description: Transaction amount
          example: 123.45
          minimum: 0
        transaction_type:
          type: string
          enum:
            - ECOM
            - AFT
          default: ECOM
          description: |
            Transaction type (defaults ECOM).

            - ECOM - refers to an e-commerce transaction (online purchase)
            - AFT - stands for Account Funding Transaction (pulling funds from a card to another account). AFT is currently supported for Visa only.
        cryptogram_type:
          type: string
          enum:
            - TAVV
            - DTVV
          default: TAVV
          description: *cryptogramTypeRef
    CardAttributes:
      type: object
      properties:
        pan:
          type: string
          maxLength: 19
          minLength: 14
          title: Primary Account Number
          description: The primary account number of the card.
          examples:
            - "4111111111111111"
        pan_alias:
          type: string
          title: PAN Alias
          description: |
            The PAN alias is a reference identifier that stores or securely holds the actual PAN value.
          examples:
            - "tok_sandbox_hhyPgvvdFfFGBnyi73TfFu"
        cvc:
          type: string
          maxLength: 4
          minLength: 3
          title: Card Verification Code
          description: |
            The card verification code of the card. It's a security measure, typically a three-digit number on the back of the card (or four digits on some cards like American Express).
          examples:
            - "123"
        cvc_alias:
          type: string
          maxLength: 35
          minLength: 30
          title: CVC Alias
          description: |
            The CVC Alias is a reference identifier that stores or securely holds the actual CVC value.
          examples:
            - "tok_sandbox_5XK62B8G2i1mTwoGR5o4tL"
        cvc_status:
          type: string
          maxLength: 10
          minLength: 3
          title: CVC Status
          description: |
            The is an indicator that CVC was present during Create Card.
          examples:
            - "active/not-set"
        exp_month:
          type: integer
          maximum: 12
          minimum: 1
          title: Expiration Month
          description: |
            The expiration month of the card, as an integer between 1 and 12, where 1 is January, and 12 is December.
        exp_year:
          type: integer
          maximum: 99
          minimum: 0
          title: Expiration Year
          description: |
            The expiration year of the card, as a 1-2 digit integer representing the decade portion of the year.
          examples:
            - 25
        cardholder:
          $ref: "#/components/schemas/Cardholder"
          description: |
            Information about the cardholder, including name, email, address, and phone. To achieve a high success rate with Amex Network Tokens, include card holder phone and email address.
        token_type:
          $ref: "#/components/schemas/TokenType"
        wallet_type:
          $ref: "#/components/schemas/WalletType"
      required:
        - pan
        - exp_month
        - exp_year
    CardAsset:
      type: object
      description: Card asset
      required:
        - type
        - download_url
      properties:
        type:
          type: string
          description: "Type of card asset"
          enum:
            - CARD_SYMBOL
            - DIGITAL_CARD_ART
            - DIGITAL_CARD_ART_BACKGROUND
          example: "CARD_SYMBOL"
        mime_type:
          type: string
          description: "MIME type of the file"
          example: "image/png"
        width:
          type: integer
          description: "Width of the image in pixel"
          example: 1536
        height:
          type: integer
          description: "Height of the image in pixel"
          example: 969
        download_url:
          type: string
          description: "URL for downloading the image"
          example: "https://assets.calm.live.verygoodsecurity.com/live/calm/assets/9018116a-e0b7-4e5b-8227-d33615632856?Expires=1752083981&Signature=bJ-Lx89Vaqfadbx4-AhXoS~Q648Kl3oS6MGiKVUsIkAEdIV6x93uY24tdcxLT5IlLVMoOb3oJkTEwUtakpuDF2ZnA72Iy37bw-x86DWg4cOH-EZWEtERFbB~AFISArH62kxIgItR-CjSByuGxNFl~q-7X2Xo-xDG4D4LewUhNRiLy2zxUmHk5L5qFegJRRFOsz8NyUaGmf8BU8TDuUnyqNGu-G8FzahJ1QQSAS3UVqUlwiMuNZDOC~ySrZQrZ65Ij8QzAPeyLzTj2FhOXU66P6wFIoLCes~qDz~Z5lFZRjRbxrpRNhueKHjCU6vmwRKZ6mZV-qloHz0D8tszs5kN8w__&Key-Pair-Id=K14FU0X3LR21JX"
    CardArt:
      type: object
      description: Card art
      properties:
        background_color:
          type: string
          description: "Background color of card art"
          example: "0x009614"
        foreground_color:
          type: string
          description: "Foreground color of card art"
          example: "0x009614"
        label_color:
          type: string
          description: "Label color of card art"
          example: "0x009614"
        issuer_name:
          type: string
          description: "Issuer of the card"
          example: "TEST CREDITBANK"
        contact_website:
          type: string
          description: "Contact website of the card"
          example: "www.example.com"
        contact_number:
          type: string
          description: "Contact phone number of the card"
          example: "987654321"
        contact_name:
          type: string
          description: "Contact name of the card"
          example: "XYZ Bank"
        short_description:
          type: string
          description: "Short description of the card"
          example: "short description"
        long_description:
          type: string
          description: "Long description of the card"
          example: "long description"
        assets:
          type: array
          items:
            $ref: '#/components/schemas/CardAsset'
    CardResourceAttributes:
      type: object
      title: CardResourceAttributes
      description: Full card information with extra fields like bin, last4, capabilities etc
      allOf:
        - $ref: "#/components/schemas/CardAttributes"
        - properties:
            bin:
              type: string
              minLength: 6
              maxLength: 8
              description: The leading six or eight digits of the related card are the issuer identification number (IIN) sometimes referred to as the bank identification number (BIN).
            first8:
              type: string
              minLength: 8
              maxLength: 8
              description: 8 character Bank Identification Number (BIN). The first8 field will be returned in the card object only for Visa and Mastercard cards.
            last4:
              type: string
              minLength: 4
              maxLength: 4
              description: Last 4 characters of the primary account number (pan/fpan)
            card_fingerprint:
              type: string
              description: Card Fingerprint
            cvc_status:
              type: string
              description: CVC Status
            capabilities:
              items:
                type: string
                enum:
                  - card-updates
                  - network-tokens
                title: CardCapabilities
              type: array
              title: Capabilities
              description: |
                The capabilities a card has had activated during the creation process.
            created_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
            card_brand:
              type: string
              description: The name of the card brand.
              example: "MASTERCARD"
            card_type:
              type: string
              description: The card type (credit, debit or prepaid).
              example: "CREDIT"
            enriched_attributes:
              $ref: "#/components/schemas/EnrichedCardAttributes"
              description: "Enriched card attributes containing additional metadata about the card. \nThis data provides detailed information about the card's capabilities, issuer \ndetails, and transaction support features.\n"
          required:
            - bin
            - first8
            - last4
            - created_at
            - updated_at
          type: object
    Address:
      properties:
        address1:
          type: string
          maxLength: 255
          description: The first line of the address related to the card.
          example: 123 Main Street
        address2:
          type: string
          maxLength: 255
          description: The second line of the address related to the card.
          example: Unit 2
        address3:
          type: string
          maxLength: 255
          description: The third line of the address related to the card.
        address4:
          type: string
          maxLength: 255
          description: The fourth line of the address related to the card.
        city:
          type: string
          maxLength: 255
          description: The city of the address related to the card.
          example: New York
        region:
          type: string
          maxLength: 255
          description: The region of the address related to the card.
          example: NY
        postal_code:
          type: string
          maxLength: 10
          description: The postal code of the address related to the card.
          example: 94102
        country:
          type: string
          maxLength: 3
          minLength: 2
          description: |
            The country of the address related to the card. This must be the ISO 3166-1 alpha-2 or the ISO 3166-1 alpha-3 code. (ISO 3166-1)[https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3]
          example: US
      type: object
      title: Address
      examples:
        - |2-
            {
                "address1": "123 Main Street",
                "address2": "Suite 404",
                "city": "New York"
                "region": "New York",
                "postal_code": "11111",
                "country": "US"
            }
    CardResourceRequest:
      type: object
      properties:
        data:
          type: object
          properties:
            attributes:
              $ref: "#/components/schemas/CardAttributes"
            meta:
              $ref: "#/components/schemas/CardResourceMetadata"
          required:
            - attributes
      description: The card information.
      additionalProperties: false
      required:
        - data
    CardCheckResourceResponse:
      title: CardCheckResourceResponse
      type: object
      properties:
        data:
          $ref: "#/components/schemas/CardUpdateResource"
        metadata:
          $ref: "#/components/schemas/MetadataResponse"
        jsonapi:
          $ref: "#/components/schemas/JsonApiVersion"
      additionalProperties: false
      required:
        - data
    CardResourceResponse:
      title: CardResourceResponse
      type: object
      properties:
        data:
          allOf:
            - $ref: "#/components/schemas/BaseResource"
            - properties:
                id:
                  type: string
                  title: id
                  description: Resource ID
                type:
                  type: string
                  title: Type
                  default: cards
                attributes:
                  $ref: "#/components/schemas/CardResourceAttributes"
                meta:
                  $ref: "#/components/schemas/CardResourceMetadata"
              type: object
        included:
          items:
            $ref: "#/components/schemas/IncludedResource"
          type: array
          title: IncludedResources
          description: Complete resource objects for resources related to the primary data in the response.
        metadata:
          $ref: "#/components/schemas/MetadataResponse"
        jsonapi:
          $ref: "#/components/schemas/JsonApiVersion"
      additionalProperties: false
      required:
        - data
    NetworkTokenResourceResponse:
      title: NetworkTokenResourceResponse
      type: object
      properties:
        data:
          $ref: "#/components/schemas/NetworkTokenResource"
      additionalProperties: false
      required:
        - data
    CardUpdateSubscriptionResourceResponse:
      title: CardUpdateSubscriptionResourceResponse
      type: object
      properties:
        data:
          $ref: "#/components/schemas/CardUpdateSubscriptionResource"
      additionalProperties: false
      required:
        - data
    MetadataResponse:
      type: object
      title: MetadataResponse
      properties:
        observability:
          $ref: "#/components/schemas/Observability"
    Observability:
      type: object
      title: Observability
      properties:
        trace_id:
          type: string
        client_id:
          type: string
        vault_id:
          type: string
        account_id:
          type: string
        fingerprint:
          type: string
    IncludedResourceType:
      type: string
      enum:
        - card_updates
        - card_update_subscriptions
        - network_tokens
    BaseIncludedResource:
      type: object
      properties:
        type:
          $ref: "#/components/schemas/IncludedResourceType"
    IncludedResource:
      allOf:
        - $ref: "#/components/schemas/BaseIncludedResource"
        - oneOf:
            - $ref: "#/components/schemas/CardUpdateResource"
            - $ref: "#/components/schemas/CardUpdateSubscriptionResource"
            - $ref: "#/components/schemas/NetworkTokenResource"
      discriminator:
        propertyName: type
        mapping:
          card_updates: "#/components/schemas/CardUpdateResource"
          card_update_subscriptions: "#/components/schemas/CardUpdateSubscriptionResource"
          network_tokens: "#/components/schemas/NetworkTokenResource"
    UpdatedCardFieldResource:
      type: object
      title: UpdatedCardFieldResource
      properties:
        field_name:
          type: string
        old_value:
          type: string
        new_value:
          type: string
      required:
        - field_name
        - old_value
        - new_value
    CardUpdateResource:
      type: object
      description: An event representing an update from the card network pertaining to the related card and card update subscription.
      properties:
        id:
          type: string
          description: ID of card update subcription.
        type:
          $ref: "#/components/schemas/IncludedResourceType"
        attributes:
          type: object
          properties:
            occurred_at:
              type: string
              format: datetime
            reason_code:
              type: string
            reason_text:
              type: string
            changed_fields:
              type: array
              items:
                type: string
            updated_values:
              type: array
              title: CardUpdateResourceUpdatedValues
              items:
                $ref: "#/components/schemas/UpdatedCardFieldResource"
            event:
              type: string
              enum:
                - updated
                - expired
                - closed
                - non-participating
                - contact-cardholder-advice
                - unknown
                - enrolled
                - enrollment-failed
                - opt-out
              description: |
                - updated - **Account number change message**: This event is triggered when a cardholder opens a new account with a participating issuer or when a new card is issued. For e.g. this could be due to new account creation, lost or stolen card, or when a card holder gets upgraded to Platinum or downgraded, or, due to a portfolio change (one bank to another).
                - expired - **Expiration date change** This event denotes an expiration date change event. Whenever the card expires but has the same PAN, then, a new expiration date is issued. This event is an indication that the card expired (and so a new date is issued). Typically, cards have an expiration date of 2, 3 or x years (it used to be 5 but we rarely see them these days). Sometimes, an issuer can have an expiration for 1 year (for brand new card holders as they do not have enough credit).
                - closed - **Closed account advice** This event is triggered when the issuer reports the closure of the cardholder's account i.e. cardholder's account associated with the particular card is no longer active/closed providing an important update for merchants to keep their records accurate and avoid attempting transactions with invalid or closed accounts.
                - non-participating - **Non-participating BIN** This event represents a non-participating BIN event, indicating that cards linked to these BINs will not receive updates through the account updater service. i.e. BIN of a particular card is not participating in the account updater service and merchants subscribed to account updater will not receive updates for cards associated with non-participating BINs.
                - contact-cardholder-advice - **Contact cardholder advice** This event indicates the issuer is letting the merchant know that something has changed and the merchant should force the customer to key enter the credential and the update will not be shared via the account updater channel for the merchant. In short the merchant must contact the cardholder for more information or clarification.
                - unknown - **Account not found response from a participating BIN** This event indicates that the card is eligible for automatic updates, but no match was found for this account.
                - enrolled - This event is triggered when a card is successfully enrolled in account updater or when the network confirms that the card status remains unchanged. **Successfully enrolled** - The card is successfully enrolled for updates from the networks. **Match made, account number and expiration date unchanged** - This event implies that the card is already enrolled for account updater services, confirming the card's account number and expiration date haven't changed (matched) since the last card update.
                - enrollment-failed - This event is triggered when a card was unsuccessfully enrolled in account updater.
                - opt-out - **Cardholder Opt-Out Note** (Stop Advice) is placed on a card.
            received_at:
              type: string
              format: datetime
              description: Timestamp of when the event was received from the network.
          required:
            - received_at
            - occurred_at
            - event
            - changed_fields
            - updated_values
          title: CardUpdateResourceAttributes
      additionalProperties: false
    CardUpdateSubscriptionResource:
      type: object
      description: An object representing a card account updater subscription. A card update subscription receives updates from the card network when the card is renewed or replaced.
      properties:
        id:
          type: string
          description: ID of card update subcription.
        type:
          $ref: "#/components/schemas/IncludedResourceType"
        attributes:
          type: object
          properties:
            bin:
              type: string
              format: \d{6,10}
              description: The leading six or eight digits of the related card are the issuer identification number (IIN) sometimes referred to as the bank identification number (BIN).
            created_at:
              type: string
              format: date-time
            state:
              type: string
              enum:
                - enrolled
                - failed
              description: State of the card update subscription.
            updated_at:
              type: string
              format: date-time
    NetworkTokenAndCryptogramResource:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              title: id
              description: Resource ID
            type:
              type: string
              enum:
                - network_tokens
            attributes:
              allOf:
                - type: object
                  properties:
                    cryptogram:
                      $ref: "#/components/schemas/CryptogramAttributes"
                - $ref: "#/components/schemas/NetworkTokenAttributes"
    NetworkTokenAttributes:
      type: object
      properties:
        payment_account_reference:
          type: string
          title: Payment Account Reference
        network_token:
          type: string
          title: The network token PAN
          minLength: 13
          maxLength: 19
        last4:
          type: string
          title: Network Token Last4
          maxLength: 4
        bin:
          type: string
          title: Network Token Bin
          minLength: 6
          maxLength: 10
        exp_month:
          type: integer
          title: Expiration Month
          minimum: 1
          maximum: 12
        exp_year:
          type: integer
          title: Expiration Year
          minimum: 0
          maximum: 99
        created_at:
          type: string
          title: Created At
          format: date-time
        updated_at:
          type: string
          title: Updated At
          format: date-time
        state:
          type: string
          title: State
        reason_code:
          type: string
        reason_text:
          type: string
      required:
        - payment_account_reference
        - network_token
        - last4
        - bin
        - exp_month
        - exp_year
        - created_at
        - updated_at
        - state
      title: NetworkTokenSchema
    NetworkTokenResource:
      properties:
        id:
          type: string
          title: id
          description: Resource ID
        type:
          $ref: "#/components/schemas/IncludedResourceType"
        attributes:
          $ref: "#/components/schemas/NetworkTokenAttributes"
        meta:
          type: object
          title: meta
          description: Information about the card meta, including card art
          properties:
            card_art:
              $ref: "#/components/schemas/CardArt"
              description: |
                Card art
        relationships:
          additionalProperties:
            properties:
              links:
                anyOf:
                  - properties:
                      self:
                        anyOf:
                          - type: string
                            minLength: 1
                            format: uri
                          - properties:
                              href:
                                anyOf:
                                  - type: string
                                    minLength: 1
                                    format: uri
                                  - type: "null"
                                title: href
                              rel:
                                anyOf:
                                  - type: string
                                  - type: "null"
                                title: link relation type
                              describedby:
                                anyOf:
                                  - type: string
                                  - type: "null"
                                title: |
                                  link to a description of the link relation type
                              title:
                                anyOf:
                                  - type: string
                                  - type: "null"
                                title: link title
                              type:
                                anyOf:
                                  - type: string
                                  - type: "null"
                                title: link media type
                              hreflang:
                                anyOf:
                                  - type: string
                                  - items:
                                      type: string
                                    type: array
                                  - type: "null"
                                title: link language
                              meta:
                                anyOf:
                                  - type: object
                                  - type: "null"
                                title: meta
                            type: object
                            title: LubeLink
                            description: JSON:API Link
                          - type: "null"
                        title: relationship link
                      related:
                        anyOf:
                          - type: string
                            minLength: 1
                            format: uri
                          - properties:
                              href:
                                anyOf:
                                  - type: string
                                    minLength: 1
                                    format: uri
                                  - type: "null"
                                title: href
                              rel:
                                anyOf:
                                  - type: string
                                  - type: "null"
                                title: link relation type
                              describedby:
                                anyOf:
                                  - type: string
                                  - type: "null"
                                title: |
                                  link to a description of the link relation type
                              title:
                                anyOf:
                                  - type: string
                                  - type: "null"
                                title: link title
                              type:
                                anyOf:
                                  - type: string
                                  - type: "null"
                                title: link media type
                              hreflang:
                                anyOf:
                                  - type: string
                                  - items:
                                      type: string
                                    type: array
                                  - type: "null"
                                title: link language
                              meta:
                                anyOf:
                                  - type: object
                                  - type: "null"
                                title: meta
                            type: object
                            title: LubeLink
                            description: JSON:API Link
                          - type: "null"
                        title: related resource link
                    type: object
                    title: LubeRelationLink
                  - type: "null"
              data:
                anyOf:
                  - properties:
                      id:
                        type: string
                        title: id
                        description: Resource ID
                      type:
                        type: string
                        title: type
                        description: Resource type
                      meta:
                        type: object
                        title: meta
                    type: object
                    required:
                      - id
                      - type
                    title: LubeResourceId
                    description: JSON:API Resource Identifier
                  - items:
                      properties:
                        id:
                          type: string
                          title: id
                          description: Resource ID
                        type:
                          type: string
                          title: type
                          description: Resource type
                        meta:
                          type: object
                          title: meta
                      type: object
                      required:
                        - id
                        - type
                      title: LubeResourceId
                      description: JSON:API Resource Identifier
                    type: array
                  - type: "null"
                title: Data
              meta:
                anyOf:
                  - type: object
                  - type: "null"
                title: Meta
            type: object
            title: LubeRel
            description: JSON:API Relationship
          type: object
          title: Relationships
          description: |
            Information about other services or capabilities that are related to this network token.
        links:
          anyOf:
            - additionalProperties:
                anyOf:
                  - type: string
                    minLength: 1
                    format: uri
                  - properties:
                      href:
                        anyOf:
                          - type: string
                            minLength: 1
                            format: uri
                          - type: "null"
                        title: href
                      rel:
                        anyOf:
                          - type: string
                          - type: "null"
                        title: link relation type
                      describedby:
                        anyOf:
                          - type: string
                          - type: "null"
                        title: |
                          link to a description of the link relation type
                      title:
                        anyOf:
                          - type: string
                          - type: "null"
                        title: link title
                      type:
                        anyOf:
                          - type: string
                          - type: "null"
                        title: link media type
                      hreflang:
                        anyOf:
                          - type: string
                          - items:
                              type: string
                            type: array
                          - type: "null"
                        title: link language
                      meta:
                        anyOf:
                          - type: object
                          - type: "null"
                        title: meta
                    type: object
                    title: LubeLink
                    description: JSON:API Link
                  - type: string
                  - type: "null"
              type: object
            - type: "null"
          title: Links
      additionalProperties: false
      type: object
      required:
        - id
        - type
      title: NetworkTokenResource
    BaseResource:
      properties:
        relationships:
          additionalProperties:
            properties:
              links:
                anyOf:
                  - properties:
                      self:
                        anyOf:
                          - type: string
                            minLength: 1
                            format: uri
                          - properties:
                              href:
                                anyOf:
                                  - type: string
                                    minLength: 1
                                    format: uri
                                  - type: "null"
                                title: href
                              rel:
                                anyOf:
                                  - type: string
                                  - type: "null"
                                title: link relation type
                              describedby:
                                anyOf:
                                  - type: string
                                  - type: "null"
                                title: |
                                  link to a description of the link relation type
                              title:
                                anyOf:
                                  - type: string
                                  - type: "null"
                                title: link title
                              type:
                                anyOf:
                                  - type: string
                                  - type: "null"
                                title: link media type
                              hreflang:
                                anyOf:
                                  - type: string
                                  - items:
                                      type: string
                                    type: array
                                  - type: "null"
                                title: link language
                              meta:
                                anyOf:
                                  - type: object
                                  - type: "null"
                                title: meta
                            type: object
                            title: LubeLink
                            description: JSON:API Link
                          - type: "null"
                        title: relationship link
                      related:
                        anyOf:
                          - type: string
                            minLength: 1
                            format: uri
                          - properties:
                              href:
                                anyOf:
                                  - type: string
                                    minLength: 1
                                    format: uri
                                  - type: "null"
                                title: href
                              rel:
                                anyOf:
                                  - type: string
                                  - type: "null"
                                title: link relation type
                              describedby:
                                anyOf:
                                  - type: string
                                  - type: "null"
                                title: |
                                  link to a description of the link relation type
                              title:
                                anyOf:
                                  - type: string
                                  - type: "null"
                                title: link title
                              type:
                                anyOf:
                                  - type: string
                                  - type: "null"
                                title: link media type
                              hreflang:
                                anyOf:
                                  - type: string
                                  - items:
                                      type: string
                                    type: array
                                  - type: "null"
                                title: link language
                              meta:
                                anyOf:
                                  - type: object
                                  - type: "null"
                                title: meta
                            type: object
                            title: LubeLink
                            description: JSON:API Link
                          - type: "null"
                        title: related resource link
                  - type: object
                    title: LubeRelationLink
                  - type: "null"
              data:
                anyOf:
                  - properties:
                      id:
                        type: string
                        title: id
                        description: Resource ID
                      type:
                        type: string
                        title: type
                        description: Resource type
                      meta:
                        type: object
                        title: meta
                    type: object
                    required:
                      - id
                      - type
                    title: LubeResourceId
                    description: JSON:API Resource Identifier
                  - items:
                      properties:
                        id:
                          type: string
                          title: id
                          description: Resource ID
                        type:
                          type: string
                          title: type
                          description: Resource type
                        meta:
                          type: object
                          title: meta
                      type: object
                      required:
                        - id
                        - type
                      title: LubeResourceId
                      description: JSON:API Resource Identifier
                    type: array
                  - type: "null"
                title: Data
              meta:
                anyOf:
                  - type: object
                  - type: "null"
                title: Meta
            type: object
            title: LubeRel
            description: JSON:API Relationship
          type: object
          title: Relationships
          description: |
            Information about other services or capabilities that are related to this network token.
        links:
          anyOf:
            - additionalProperties:
                anyOf:
                  - type: string
                    minLength: 1
                    format: uri
                  - properties:
                      href:
                        anyOf:
                          - type: string
                            minLength: 1
                            format: uri
                          - type: "null"
                        title: href
                      rel:
                        anyOf:
                          - type: string
                          - type: "null"
                        title: link relation type
                      describedby:
                        anyOf:
                          - type: string
                          - type: "null"
                        title: |
                          link to a description of the link relation type
                      title:
                        anyOf:
                          - type: string
                          - type: "null"
                        title: link title
                      type:
                        anyOf:
                          - type: string
                          - type: "null"
                        title: link media type
                      hreflang:
                        anyOf:
                          - type: string
                          - items:
                              type: string
                            type: array
                          - type: "null"
                        title: link language
                      meta:
                        anyOf:
                          - type: object
                          - type: "null"
                        title: meta
                    type: object
                    title: LubeLink
                    description: JSON:API Link
                  - type: string
                  - type: "null"
              type: object
            - type: "null"
          title: Links
      type: object
      title: BaseResource
    CardUpdateWebhook:
      properties:
        description:
          type: string
          title: Description
        details:
          properties:
            card_id:
              type: string
              title: Card Id
            new_account_number:
              type: string
              title: New Account Number
            new_expiration_date:
              type: string
              title: New Expiration Date
            occured_at:
              type: string
              title: Occured At
              format: date-time
            old_account_number:
              type: string
              title: Old Account Number
            card_fingerprint:
              type: string
              title: Card Fingerprint
            old_expiration_date:
              type: string
              title: Old Expiration Date
          type: object
          required:
            - card_id
            - new_account_number
            - new_expiration_date
            - occured_at
            - old_account_number
            - old_expiration_date
          title: Details
        event:
          type: string
          title: Event
        fingerprint:
          type: string
          title: Fingerprint
        grouping:
          type: string
          title: Grouping
        id:
          type: string
          title: Id
        integration_id:
          type: string
          title: Integration Id
        occurrence:
          type: integer
          title: Occurrence
        org_id:
          type: string
          title: Org Id
        producer:
          properties:
            application_name:
              type: string
              title: Application Name
            application_protocol:
              type: string
              title: Application Protocol
          type: object
          required:
            - application_name
            - application_protocol
          title: Producer
        scope:
          type: string
          title: Scope
        summary:
          type: string
          title: Summary
        tenant:
          type: string
          title: Tenant
        timestamp:
          type: string
          title: Timestamp
      type: object
      required:
        - description
        - details
        - event
        - fingerprint
        - grouping
        - id
        - integration_id
        - occurrence
        - org_id
        - producer
        - scope
        - summary
        - tenant
        - timestamp
      title: CardUpdateWebhook
    Cardholder:
      type: object
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
          description: The cardholder name.
          examples:
            - John Q. Public
        company:
          type: string
          maxLength: 255
          title: Company
          description: Company name.
          examples:
            - A Corp, LLC
        phone:
          type: string
          maxLength: 16
          title: Phone
          description: The phone number related to the card.
        email:
          type: string
          format: email
          description: Email address of the account holder.
          example: "bob.smith@gmail.com"
        address:
          $ref: "#/components/schemas/Address"
      description: |
        Information about the cardholder, including name, email, address, and phone. To achieve a high success rate with Amex Network Tokens, include card holder phone and email address.
    ErrorForbiddenResponse:
      properties:
        errors:
          items:
            properties:
              status:
                type: integer
                title: Status
              details:
                type: string
                title: Details
              title:
                type: string
                title: Title
            type: object
            title: Error
          type: array
          title: Errors
          description: A list of errors
        jsonapi:
          $ref: "#/components/schemas/JsonApiVersion"
      type: object
      title: ErrorForbiddenResponse
    ErrorResponse:
      properties:
        errors:
          items:
            properties:
              path:
                type: string
                title: Path
              summary:
                type: string
                title: Summary
              detail:
                type: string
                title: Detail
              error_code:
                type: string
                title: Error Code
              fingerprint:
                type: string
                title: string
            type: object
            title: Error
          type: array
          title: Errors
          description: A list of errors
          required:
            - summary
            - detail
            - error_code
        meta:
          anyOf:
            - type: object
          title: Meta
        links:
          anyOf:
            - additionalProperties:
                anyOf:
                  - type: string
                  - properties:
                      href:
                        anyOf:
                          - type: string
                            minLength: 1
                            format: uri
                          - type: "null"
                        title: href
                      rel:
                        anyOf:
                          - type: string
                          - type: "null"
                        title: link relation type
                      describedby:
                        anyOf:
                          - type: string
                          - type: "null"
                        title: link to a description of the link relation type
                      title:
                        anyOf:
                          - type: string
                          - type: "null"
                        title: link title
                      type:
                        anyOf:
                          - type: string
                          - type: "null"
                        title: link media type
                      hreflang:
                        anyOf:
                          - type: string
                          - items:
                              type: string
                            type: array
                          - type: "null"
                        title: link language
                      meta:
                        anyOf:
                          - type: object
                          - type: "null"
                        title: meta
                    type: object
                    title: LubeLink
                    description: JSON:API Link
                  - type: "null"
              type: object
          title: Links
        included:
          anyOf:
            - items:
                properties:
                  id:
                    type: string
                    title: id
                    description: Resource ID
                  type:
                    type: string
                    title: type
                    description: Resource type
                  attributes:
                    anyOf:
                      - properties: {}
                        additionalProperties: true
                        type: object
                        title: LubeAttributes
                        description: |
                          Members of the LubeAttributes object ("attributes") represent information about the resource object in which it's defined.


                          The keys for Attributes MUST NOT be:


                              relationships
                              links
                              id
                              type
                      - type: "null"
                  relationships:
                    anyOf:
                      - additionalProperties:
                          properties:
                            links:
                              anyOf:
                                - properties:
                                    self:
                                      anyOf:
                                        - type: string
                                          minLength: 1
                                          format: uri
                                        - properties:
                                            href:
                                              anyOf:
                                                - type: string
                                                  minLength: 1
                                                  format: uri
                                                - type: "null"
                                              title: href
                                            rel:
                                              anyOf:
                                                - type: string
                                                - type: "null"
                                              title: link relation type
                                            describedby:
                                              anyOf:
                                                - type: string
                                                - type: "null"
                                              title: |
                                                link to a description of the link relation type
                                            title:
                                              anyOf:
                                                - type: string
                                                - type: "null"
                                              title: link title
                                            type:
                                              anyOf:
                                                - type: string
                                                - type: "null"
                                              title: link media type
                                            hreflang:
                                              anyOf:
                                                - type: string
                                                - items:
                                                    type: string
                                                  type: array
                                                - type: "null"
                                              title: link language
                                            meta:
                                              anyOf:
                                                - type: object
                                                - type: "null"
                                              title: meta
                                          type: object
                                          title: LubeLink
                                          description: JSON:API Link
                                        - type: "null"
                                      title: relationship link
                                    related:
                                      anyOf:
                                        - type: string
                                          minLength: 1
                                          format: uri
                                        - properties:
                                            href:
                                              anyOf:
                                                - type: string
                                                  minLength: 1
                                                  format: uri
                                                - type: "null"
                                              title: href
                                            rel:
                                              anyOf:
                                                - type: string
                                                - type: "null"
                                              title: link relation type
                                            describedby:
                                              anyOf:
                                                - type: string
                                                - type: "null"
                                              title: |
                                                link to a description of the link relation type
                                            title:
                                              anyOf:
                                                - type: string
                                                - type: "null"
                                              title: link title
                                            type:
                                              anyOf:
                                                - type: string
                                                - type: "null"
                                              title: link media type
                                            hreflang:
                                              anyOf:
                                                - type: string
                                                - items:
                                                    type: string
                                                  type: array
                                                - type: "null"
                                              title: link language
                                            meta:
                                              anyOf:
                                                - type: object
                                                - type: "null"
                                              title: meta
                                          type: object
                                          title: LubeLink
                                          description: JSON:API Link
                                        - type: "null"
                                      title: related resource link
                                  type: object
                                  title: LubeRelationLink
                                - type: "null"
                            data:
                              anyOf:
                                - properties:
                                    id:
                                      type: string
                                      title: id
                                      description: Resource ID
                                    type:
                                      type: string
                                      title: type
                                      description: Resource type
                                    meta:
                                      type: object
                                      title: meta
                                    lid:
                                      anyOf:
                                        - type: string
                                        - type: "null"
                                      title: Lid
                                  type: object
                                  required:
                                    - id
                                    - type
                                  title: LubeResourceId
                                  description: JSON:API Resource Identifier
                                - items:
                                    properties:
                                      id:
                                        type: string
                                        title: id
                                        description: Resource ID
                                      type:
                                        type: string
                                        title: type
                                        description: Resource type
                                      meta:
                                        type: object
                                        title: meta
                                      lid:
                                        anyOf:
                                          - type: string
                                          - type: "null"
                                        title: Lid
                                    type: object
                                    required:
                                      - id
                                      - type
                                    title: LubeResourceId
                                    description: JSON:API Resource Identifier
                                  type: array
                                - type: "null"
                              title: Data
                            meta:
                              anyOf:
                                - type: object
                                - type: "null"
                              title: Meta
                          type: object
                          title: LubeRel
                          description: JSON:API Relationship
                        type: object
                      - type: "null"
                    title: Relationships
                  links:
                    anyOf:
                      - additionalProperties:
                          anyOf:
                            - type: string
                              minLength: 1
                              format: uri
                            - properties:
                                href:
                                  anyOf:
                                    - type: string
                                      minLength: 1
                                      format: uri
                                    - type: "null"
                                  title: href
                                rel:
                                  anyOf:
                                    - type: string
                                    - type: "null"
                                  title: link relation type
                                describedby:
                                  anyOf:
                                    - type: string
                                    - type: "null"
                                  title: |
                                    link to a description of the link relation type
                                title:
                                  anyOf:
                                    - type: string
                                    - type: "null"
                                  title: link title
                                type:
                                  anyOf:
                                    - type: string
                                    - type: "null"
                                  title: link media type
                                hreflang:
                                  anyOf:
                                    - type: string
                                    - items:
                                        type: string
                                      type: array
                                    - type: "null"
                                  title: link language
                                meta:
                                  anyOf:
                                    - type: object
                                    - type: "null"
                                  title: meta
                              type: object
                              title: LubeLink
                              description: JSON:API Link
                            - type: string
                            - type: "null"
                        type: object
                      - type: "null"
                    title: Links
                  meta:
                    anyOf:
                      - type: object
                      - type: "null"
                    title: Meta
                type: object
                required:
                  - id
                  - type
                title: LubeResource
                description: A single resource. The only JSON:API required field is type
              type: array
          title: Included
        jsonapi:
          $ref: "#/components/schemas/JsonApiVersion"
      type: object
      title: ErrorResponse
    CreateConfigurationRequest:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - type
            - attributes
          properties:
            type:
              type: string
              enum:
                - configuration
            attributes:
              $ref: "#/components/schemas/BaseConfiguration"
    TokenType:
      type: string
      description: The type of token being used for the card.
      enum:
        - dpan
        - mpan
        - pan
      example: dpan
    WalletType:
      type: string
      description: The digital wallet from which the card request originated.
      enum:
        - apple_pay
        - google_pay
      example: apple_pay
    CardResourceMetadata:
      type: object
      description: Non-standard meta-information about the card resource.
      example:
        customerID: 1234
    EnrichedCardAttributes:
      type: object
      description: Enriched card attributes from the card-attributes service
      properties:
        card_properties:
          type: object
          properties:
            card_number_length:
              type: integer
              description: |
                The length of the Primary Account Number (PAN) printed on the front of the card. Available only for Card Attributes service subscribers.
              example: 16
            card_segment_type:
              type: string
              description: Indicator of Business, Consumer, Commercial, Government BINs. Available only for Card Attributes service subscribers.
              example: "PERSONAL"
            virtual_card:
              type: boolean
              description: |
                Indicates if the given BIN range supports virtual card creation. Available only for Card Attributes service subscribers.
              example: false
            prepaid_card:
              type: boolean
              description: |
                Indicates a fixed funding source for a card but not necessarily associated with the consumer's checking account. Available only for Card Attributes service subscribers.
              example: false
            product_name:
              type: string
              description: |
                The card product name according to the card brand (e.g., Visa Signature, Visa Infinite, Visa Classic). Available only for Card Attributes service subscribers.
              example: "Visa Signature"
            issuer_bin:
              type: string
              description: Bank Identification Number (BIN) of the issuer of the account. Available only for Card Attributes service subscribers.
              example: "22048890"
            country_letter_code:
              type: string
              description: |
                The issuing country's ISO 3166 code in either two-letter (e.g., US) or three-letter (e.g., USA) format. Available only for Card Attributes service subscribers.
              example: "US"
            country_name:
              type: string
              description: Name of the issuing country. Available only for Card Attributes service subscribers.
              example: "UNITED STATES"
            country_numeric:
              type: integer
              description: ISO 3166 numeric country code of the issuing country. Available only for Card Attributes service subscribers.
              example: 840
        card_capabilities:
          type: object
          properties:
            reloadable:
              type: boolean
              description: Indicator of reloadable or non-reloadable prepaid. Available only for Card Attributes service subscribers.
              example: false
            hsa:
              type: boolean
              description: Indicates a card attached to a Health Savings Account. Available only for Card Attributes service subscribers.
              example: true
            fsa:
              type: boolean
              description: Indicates a card attached to Flexible Spending Account. Available only for Card Attributes service subscribers.
              example: false
            ebt:
              type: boolean
              description: Indicates the BIN has Electronic Benefits Transfer (EBT) capabilities. Available only for Card Attributes service subscribers.
              example: false
        bank:
          type: object
          properties:
            issuer_name:
              type: string
              description: Name of the issuing organization/bank.
              example: "U.S. EQUITY ADVANTAGE, INC."
            issuer_phone_number:
              type: string
              description: Phone number of the issuing organization/bank. Available only for Card Attributes service subscribers.
              example: "1-800-123-4567"
            issuer_website:
              type: string
              description: Website of the issuing organization/bank. Available only for Card Attributes service subscribers.
              example: "https://www.examplebank.com"
        additional_card_brands:
          type: array
          description: Additional card brands, if any, associated with the card. Available only for Card Attributes service subscribers.
          items:
            type: object
            required:
              - card_brand
            properties:
              card_brand:
                type: string
                description: The name of the additional card brand. Available only for Card Attributes service subscribers.
                example: "BANCONTACT"
        interchange:
          type: object
          properties:
            regulated:
              type: string
              description: Indicator of the presence of an interchange regulation on a BIN. Available only for Card Attributes service subscribers.
              example: "NONREGULATED"
  parameters:
    account-id:
      in: path
      name: account-id
      schema:
        type: string
      example: ACTasdf1234
      required: true
    configuration-id:
      in: path
      name: configuration-id
      example: network.capability.setting
      schema:
        type: string
      required: true
    auth-header:
      in: header
      name: Authorization
      description: Bearer token for authentication.
      example: Bearer <JWT_TOKEN>
      schema:
        type: string
      required: true
    content-type:
      in: header
      name: Content-Type
      description: Content type of a request to CMP
      example: application/vnd.api+json
      schema:
        type: string
        enum: [application/vnd.api+json]
      required: true
