Moov Wallets API

openapi: 3.2.0
info:
  title: Moov Wallets API
  version: '1.0'
  description: 'Operations tagged Wallets across 3 of this provider''s published API definitions: moov-api-v2026.01.00-openapi.yml, moov-openapi.yml, moov-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.moov.io
  description: Production API host
  variables: {}
tags:
- name: Wallets
paths:
  /accounts/{accountID}/wallets:
    post:
      operationId: createWallet
      description: 'Create a new wallet for an account. You can specify optional attributes such as a display name and description to specify the intended use of the wallet. This will generate a new moov-wallet payment method.


        Read our Moov wallets guide to learn more.


        To access this endpoint using an access token

        you''ll need to specify the `/accounts/{accountID}/wallets.write` scope.'
      parameters:
      - $ref: '#/components/parameters/VersionHeader'
      - name: accountID
        in: path
        required: true
        description: The Moov account ID the wallet belongs to.
        schema:
          type: string
      responses:
        '200':
          description: The request completed successfully.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Wallet'
        '400':
          description: The server could not understand the request due to invalid syntax.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        '401':
          description: The request contained missing or expired authentication.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
        '403':
          description: The user is not authorized to make the request.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
        '404':
          description: The requested resource was not found.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
        '409':
          description: The request conflicted with the current state of the target resource.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        '422':
          description: The request was well-formed, but the contents failed validation. Check the request for missing or invalid fields.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateWalletValidationError'
        '429':
          description: Request was refused due to rate limiting.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
        '500':
          description: The request failed due to an unexpected error.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
        '504':
          description: The request failed because a downstream service failed to respond.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
      tags:
      - Wallets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWallet'
      x-speakeasy-name-override: create
      security:
      - BasicAuth: []
      summary: Create wallet
      x-summary-source: derived
    get:
      operationId: listWallets
      description: 'List the wallets associated with a Moov account.


        Read our Moov wallets guide to learn more.


        To access this endpoint using an access token

        you''ll need to specify the `/accounts/{accountID}/wallets.read` scope.'
      parameters:
      - $ref: '#/components/parameters/VersionHeader'
      - $ref: '#/components/parameters/WalletListFilters.status'
      - $ref: '#/components/parameters/WalletListFilters.walletType'
      - $ref: '#/components/parameters/Pagination.skip'
      - $ref: '#/components/parameters/Pagination.count'
      - name: accountID
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request completed successfully.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Wallet'
              example:
              - walletID: 01234567-89ab-cdef-0123-456789abcdef
                availableBalance:
                  currency: USD
                  value: 1234
                  valueDecimal: '12.34'
                partnerAccountID: 65b57f28-49e9-4afb-9bf6-7e4fb6444917
                name: My Wallet
                status: active
                walletType: general
                description: For payments
                createdOn: '2025-01-21T21:32:16Z'
        '401':
          description: The request contained missing or expired authentication.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
        '403':
          description: The user is not authorized to make the request.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
        '422':
          description: The request was well-formed, but the contents failed validation. Check the request for missing or invalid fields.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWalletsValidationError'
        '429':
          description: Request was refused due to rate limiting.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
        '500':
          description: The request failed due to an unexpected error.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
        '504':
          description: The request failed because a downstream service failed to respond.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
      tags:
      - Wallets
      x-speakeasy-name-override: list
      security:
      - BasicAuth: []
      summary: List wallets
      x-summary-source: derived
    parameters:
    - $ref: '#/components/parameters/accountID'
    servers:
    - url: https://api.moov.io
      description: Production API host
      variables: {}
  /accounts/{accountID}/wallets/{walletID}:
    get:
      operationId: getWallet
      description: 'Get information on a specific wallet (e.g., the available balance).


        Read our Moov wallets guide to learn more.


        To access this endpoint using an access token

        you''ll need to specify the `/accounts/{accountID}/wallets.read` scope.'
      parameters:
      - $ref: '#/components/parameters/VersionHeader'
      - name: accountID
        in: path
        required: true
        schema:
          type: string
      - name: walletID
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/WalletID'
      responses:
        '200':
          description: The request completed successfully.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Wallet'
              example:
                walletID: 01234567-89ab-cdef-0123-456789abcdef
                availableBalance:
                  currency: USD
                  value: 1234
                  valueDecimal: '12.34'
                partnerAccountID: 65b57f28-49e9-4afb-9bf6-7e4fb6444917
                name: My Wallet
                status: active
                walletType: general
                description: For payments
                createdOn: '2025-01-21T21:32:16Z'
        '401':
          description: The request contained missing or expired authentication.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
        '403':
          description: The user is not authorized to make the request.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
        '404':
          description: The requested resource was not found.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
        '429':
          description: Request was refused due to rate limiting.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
        '500':
          description: The request failed due to an unexpected error.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
        '504':
          description: The request failed because a downstream service failed to respond.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
      tags:
      - Wallets
      x-speakeasy-name-override: get
      security:
      - BasicAuth: []
      summary: Get wallet
      x-summary-source: derived
    patch:
      operationId: updateWallet
      description: 'Update properties of an existing wallet such as name, description, status, or metadata.


        Read our Moov wallets guide to learn more.


        To access this endpoint using an access token

        you''ll need to specify the `/accounts/{accountID}/wallets.write` scope.'
      parameters:
      - $ref: '#/components/parameters/VersionHeader'
      - name: walletID
        in: path
        required: true
        description: Identifier for the wallet.
        schema:
          $ref: '#/components/schemas/WalletID'
      - name: accountID
        in: path
        required: true
        description: The Moov account ID the wallet belongs to.
        schema:
          type: string
      responses:
        '200':
          description: The request completed successfully.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Wallet'
        '400':
          description: The server could not understand the request due to invalid syntax.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        '401':
          description: The request contained missing or expired authentication.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
        '403':
          description: The user is not authorized to make the request.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
        '404':
          description: The requested resource was not found.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
        '409':
          description: The request conflicted with the current state of the target resource.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        '422':
          description: The request was well-formed, but the contents failed validation. Check the request for missing or invalid fields.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchWalletValidationError'
        '429':
          description: Request was refused due to rate limiting.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
        '500':
          description: The request failed due to an unexpected error.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
        '504':
          description: The request failed because a downstream service failed to respond.
          headers:
            x-request-id:
              required: true
              description: A unique identifier used to trace requests.
              schema:
                type: string
      tags:
      - Wallets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchWallet'
      x-speakeasy-name-override: update
      security:
      - BasicAuth: []
      summary: Update wallet
      x-summary-source: derived
    parameters:
    - $ref: '#/components/parameters/accountID'
    - $ref: '#/components/parameters/walletID'
    servers:
    - url: https://api.moov.io
      description: Production API host
      variables: {}
  /accounts/{accountID}/wallets/{walletID}/transactions:
    parameters:
    - $ref: '#/components/parameters/accountID'
    - $ref: '#/components/parameters/walletID'
    get:
      operationId: listWalletTransactions
      tags:
      - Wallets
      summary: List wallet transactions
      responses:
        '200':
          description: A list of wallet transactions.
      security:
      - bearerAuth: []
    servers:
    - url: https://api.moov.io
      description: Moov production
  /accounts/{accountID}/wallets/{walletID}/transactions/{transactionID}:
    parameters:
    - $ref: '#/components/parameters/accountID'
    - $ref: '#/components/parameters/walletID'
    - name: transactionID
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getWalletTransaction
      tags:
      - Wallets
      summary: Retrieve a wallet transaction
      responses:
        '200':
          description: The wallet transaction.
      security:
      - bearerAuth: []
    servers:
    - url: https://api.moov.io
      description: Moov production
  /accounts/{accountID}/adjustments:
    parameters:
    - $ref: '#/components/parameters/accountID'
    get:
      operationId: listAdjustments
      tags:
      - Wallets
      summary: List balance adjustments
      responses:
        '200':
          description: A list of adjustments.
      security:
      - bearerAuth: []
    servers:
    - url: https://api.moov.io
      description: Moov production
  /accounts/{accountID}/adjustments/{adjustmentID}:
    parameters:
    - $ref: '#/components/parameters/accountID'
    - name: adjustmentID
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getAdjustment
      tags:
      - Wallets
      summary: Retrieve a balance adjustment
      responses:
        '200':
          description: The adjustment.
      security:
      - bearerAuth: []
    servers:
    - url: https://api.moov.io
      description: Moov production
components:
  schemas:
    Count:
      type: integer
      format: int64
      description: Limits the maximum number of results returned, or determines the page size when used with `skip` or `cursor` for pagination.
      example: 20
    Currency:
      type: string
      pattern: ^[A-Za-z]{3}$
      description: A 3-letter ISO 4217 currency code.
      example: USD
    PatchWallet:
      type: object
      properties:
        name:
          type: string
        status:
          $ref: '#/components/schemas/WalletStatus'
        description:
          type: string
        metadata:
          $ref: '#/components/schemas/Metadata'
      example:
        name: My second wallet
        description: My new description
        metadata:
          optional: metadata
    Wallet:
      type: object
      required:
      - walletID
      - availableBalance
      - partnerAccountID
      - name
      - status
      - walletType
      - description
      - createdOn
      properties:
        walletID:
          $ref: '#/components/schemas/WalletID'
        availableBalance:
          $ref: '#/components/schemas/WalletAvailableBalance'
        partnerAccountID:
          type: string
        name:
          type: string
          description: Name of the wallet
        status:
          $ref: '#/components/schemas/WalletStatus'
        walletType:
          $ref: '#/components/schemas/WalletType'
        description:
          type: string
          description: Description of the wallet
        metadata:
          $ref: '#/components/schemas/Metadata'
        createdOn:
          type: string
          format: date-time
        closedOn:
          type: string
          format: date-time
      description: A Moov wallet to store funds for transfers.
    WalletAvailableBalance:
      type: object
      required:
      - currency
      - value
      - valueDecimal
      properties:
        currency:
          $ref: '#/components/schemas/Currency'
        value:
          type: integer
          format: int64
          description: "Quantity in the smallest unit of the specified currency. \n\nIn USD this is cents, for example, $12.04 is 1204 and $0.99 is 99."
          example: 1204
        valueDecimal:
          type: string
          pattern: ^\d+\.\d{1,9}$
    Metadata:
      type: object
      additionalProperties:
        type: string
      description: Free-form key-value pair list. Useful for storing information that is not captured elsewhere.
      example:
        optional: metadata
    WalletID:
      type: string
    Skip:
      type: integer
      format: int64
      description: The number of entries to skip when paginating a large result set.
      example: 60
    CreateWalletValidationError:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        metadata:
          type: string
    WalletType:
      type: string
      enum:
      - default
      - general
      - card-issuing
      description: "Type of a wallet.\n  - `default`: The system-generated wallet automatically created when an account is granted the wallet capability.\n  - `general`: An additional, user-defined wallet created via API or Dashboard.\n  - `card-issuing`: The system-generated wallet automatically created when an account is granted the card-issuing capability."
    PatchWalletValidationError:
      type: object
      properties:
        name:
          type: string
        status:
          type: string
        description:
          type: string
        metadata:
          type: string
    GenericError:
      type: object
      required:
      - error
      properties:
        error:
          type: string
    WalletStatus:
      type: string
      enum:
      - active
      - closed
      description: "Status of a wallet.\n  - `active`: The wallet is available for use and has an enabled payment method.\n  - `closed`: The wallet is no longer active and the corresponding payment method has been disabled."
    ListWalletsValidationError:
      type: object
      properties:
        status:
          type: string
        walletType:
          type: string
        skip:
          type: string
        count:
          type: string
    CreateWallet:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: Name of the wallet.
        description:
          type: string
          description: Description of the wallet.
        metadata:
          $ref: '#/components/schemas/Metadata'
      example:
        name: My wallet
        description: A general wallet used for my payments
        metadata:
          optional: metadata
  parameters:
    Pagination.skip:
      name: skip
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/Skip'
      explode: false
    WalletListFilters.status:
      name: status
      in: query
      required: false
      description: Optional parameter for filtering wallets by status.
      schema:
        $ref: '#/components/schemas/WalletStatus'
      explode: false
    VersionHeader:
      name: X-Moov-Version
      in: header
      required: false
      description: 'Set this header to v2026.01.00 to use the API described in this specification.

        When omitted, the server defaults to v2024.01.00, the earliest supported version, which may not match the behavior documented here.

        An unrecognized well-formed version uses the latest supported version that is not newer than the requested version, when one exists.

        For example, `v2026.08.00` uses `v2026.07.00`.

        A malformed value, such as `2022`, returns a `404` response.'
      schema:
        type: string
        enum:
        - v2026.01.00
        example: v2026.01.00
        x-speakeasy-ignore: true
      x-speakeasy-ignore: true
    Pagination.count:
      name: count
      in: query
      required: false
      description: Page size. When omitted, the server defaults to `200`.
      schema:
        $ref: '#/components/schemas/Count'
      explode: false
    WalletListFilters.walletType:
      name: walletType
      in: query
      required: false
      description: Optional parameter for filtering wallets by type.
      schema:
        $ref: '#/components/schemas/WalletType'
      explode: false
    accountID:
      name: accountID
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: The Moov account identifier.
    walletID:
      name: walletID
      in: path
      required: true
      schema:
        type: string
        format: uuid
  securitySchemes:
    BasicAuth:
      type: http
      scheme: Basic
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 access token passed as a Bearer token.
x-refined-from:
- moov-api-v2026.01.00-openapi.yml
- moov-openapi.yml
- moov-openapi.yml