openapi: 3.1.0 info: title: Moov Accounts Transfers API description: The Moov API is a RESTful financial infrastructure platform that enables developers to integrate money movement capabilities into their applications. The API supports a full range of financial operations including account management, payment method onboarding, transfers, sweeps, refunds, dispute resolution, card issuing, and payment links. It provides capabilities for accepting payments, storing funds in digital wallets, sending money between accounts, and issuing cards for spend management. Authentication uses OAuth2 access tokens with permission scopes, and the API returns JSON responses using standard HTTP response codes. version: 2026.01.00 contact: name: Moov Support url: https://docs.moov.io/ termsOfService: https://moov.io/legal/platform-agreement/ servers: - url: https://api.moov.io description: Production Server security: - bearerAuth: [] tags: - name: Transfers description: Initiate and manage money movement between Moov accounts. Supports ACH, RTP, and card rails with full lifecycle tracking. paths: /accounts/{accountID}/transfers: post: operationId: createTransfer summary: Create a transfer description: Initiate a money movement from a source payment method to a destination payment method. Transfers can move funds via ACH, RTP, or card rails. Every transfer has a source (where the money comes from) and a destination (where the money goes). tags: - Transfers parameters: - $ref: '#/components/parameters/AccountIDParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateTransferRequest' responses: '200': description: Transfer created successfully. content: application/json: schema: $ref: '#/components/schemas/Transfer' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' get: operationId: listTransfers summary: List transfers description: Retrieve the transfer history for a Moov account, with optional filters for date range, status, and transfer type. tags: - Transfers parameters: - $ref: '#/components/parameters/AccountIDParam' - $ref: '#/components/parameters/CountParam' - $ref: '#/components/parameters/SkipParam' - name: status in: query description: Filter transfers by their current status. schema: type: string enum: - created - pending - completed - failed - reversed responses: '200': description: Transfers returned successfully. content: application/json: schema: type: array items: $ref: '#/components/schemas/Transfer' '401': $ref: '#/components/responses/Unauthorized' /accounts/{accountID}/transfers/{transferID}: get: operationId: getTransfer summary: Retrieve a transfer description: Fetch the full details of a specific transfer, including its status, source, destination, amount, and rail-specific status updates. tags: - Transfers parameters: - $ref: '#/components/parameters/AccountIDParam' - $ref: '#/components/parameters/TransferIDParam' responses: '200': description: Transfer details returned successfully. content: application/json: schema: $ref: '#/components/schemas/Transfer' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' patch: operationId: updateTransferMetadata summary: Update transfer metadata description: Update the metadata associated with an existing transfer. Only custom metadata fields can be modified after a transfer is created. tags: - Transfers parameters: - $ref: '#/components/parameters/AccountIDParam' - $ref: '#/components/parameters/TransferIDParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateTransferRequest' responses: '200': description: Transfer metadata updated successfully. content: application/json: schema: $ref: '#/components/schemas/Transfer' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /accounts/{accountID}/transfer-options: post: operationId: getTransferOptions summary: Retrieve transfer options description: Get the available transfer options for a given source and destination account pair, including eligible payment rails, fees, and estimated settlement times to help users choose the best transfer method. tags: - Transfers parameters: - $ref: '#/components/parameters/AccountIDParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TransferOptionsRequest' responses: '200': description: Transfer options returned successfully. content: application/json: schema: $ref: '#/components/schemas/TransferOptions' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /accounts/{accountID}/transfers/{transferID}/cancellations: post: operationId: cancelTransfer summary: Cancel a transfer description: Attempt to cancel a pending transfer before it is processed. Cancellation is only available for transfers that have not yet been submitted to the payment rail. tags: - Transfers parameters: - $ref: '#/components/parameters/AccountIDParam' - $ref: '#/components/parameters/TransferIDParam' responses: '200': description: Transfer cancellation initiated. content: application/json: schema: $ref: '#/components/schemas/TransferCancellation' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' components: schemas: PaymentMethodOption: type: object description: A payment method option with its compatible payment rails. properties: paymentMethodID: type: string format: uuid description: Identifier of the payment method. paymentMethodType: type: string description: The type of this payment method. rails: type: array description: Eligible payment rails for this method. items: type: string enum: - ach-debit-fund - ach-debit-collect - ach-credit-standard - ach-credit-same-day - rtp-credit - card-payment UpdateTransferRequest: type: object description: Request body for updating transfer metadata. properties: metadata: type: object description: Updated custom key-value pairs for the transfer. additionalProperties: type: string CardExpiration: type: object description: Card expiration date. properties: month: type: string description: Two-digit expiration month. pattern: ^(0[1-9]|1[0-2])$ year: type: string description: Two-digit expiration year. pattern: ^\d{2}$ TransferAccountRef: type: object description: Reference to the Moov account involved in a transfer. properties: accountID: type: string format: uuid description: Unique identifier of the Moov account. email: type: string format: email description: Email address of the account holder. displayName: type: string description: Display name of the account. Address: type: object description: Physical or mailing address. properties: addressLine1: type: string description: Primary street address. addressLine2: type: string description: Secondary address line (suite, apartment, etc.). city: type: string description: City name. stateOrProvince: type: string description: Two-letter state or province code. maxLength: 2 postalCode: type: string description: Postal or ZIP code. country: type: string description: Two-letter ISO 3166-1 alpha-2 country code. maxLength: 2 Error: type: object description: Standard error response returned by the Moov API. properties: error: type: string description: Human-readable description of the error. code: type: string description: Machine-readable error code. TransferOptionsRequest: type: object description: Request body for retrieving available transfer options. required: - source - destination - amount properties: source: type: object description: The source account and optional payment method to evaluate. properties: accountID: type: string format: uuid description: Account ID of the transfer source. paymentMethodID: type: string format: uuid description: Optional specific payment method to evaluate. destination: type: object description: The destination account and optional payment method to evaluate. properties: accountID: type: string format: uuid description: Account ID of the transfer destination. paymentMethodID: type: string format: uuid description: Optional specific payment method to evaluate. amount: $ref: '#/components/schemas/Amount' TransferOptions: type: object description: Available payment rails and options for a proposed transfer. properties: sourceOptions: type: array description: Eligible source payment methods with their available rails. items: $ref: '#/components/schemas/PaymentMethodOption' destinationOptions: type: array description: Eligible destination payment methods with their available rails. items: $ref: '#/components/schemas/PaymentMethodOption' CardVerification: type: object description: Results of card verification checks. properties: cvv: type: string description: CVV verification result. enum: - match - noMatch - notChecked - unavailable addressLine1: type: string description: Address line 1 AVS verification result. enum: - match - noMatch - notChecked - unavailable postalCode: type: string description: Postal code AVS verification result. enum: - match - noMatch - notChecked - unavailable Card: type: object description: A credit or debit card linked to a Moov account as a payment source. properties: cardID: type: string format: uuid description: Unique identifier for the card. fingerprint: type: string description: Unique fingerprint identifying the underlying card number. brand: type: string description: Card network brand. enum: - Visa - Mastercard - AmericanExpress - Discover - DinersClub - JCB cardType: type: string description: Type of card. enum: - debit - credit - prepaid - unknown lastFourCardNumber: type: string description: Last four digits of the card number. pattern: ^\d{4}$ bin: type: string description: First six digits of the card number (Bank Identification Number). expiration: $ref: '#/components/schemas/CardExpiration' holderName: type: string description: Name of the cardholder as it appears on the card. billingAddress: $ref: '#/components/schemas/Address' cardVerification: $ref: '#/components/schemas/CardVerification' issuer: type: string description: Name of the card-issuing financial institution. issuerCountry: type: string description: Two-letter ISO country code of the card issuer. maxLength: 2 createdOn: type: string format: date-time description: ISO 8601 timestamp when the card was linked. updatedOn: type: string format: date-time description: ISO 8601 timestamp when the card was last updated. Wallet: type: object description: A Moov digital wallet that holds funds on the platform for an account. Wallets serve as intermediate stores of value for money movement. properties: walletID: type: string format: uuid description: Unique identifier for the wallet. availableBalance: $ref: '#/components/schemas/Amount' createdOn: type: string format: date-time description: ISO 8601 timestamp when the wallet was created. updatedOn: type: string format: date-time description: ISO 8601 timestamp when the wallet was last updated. TransferCancellation: type: object description: A cancellation request for a pending transfer. properties: cancellationID: type: string format: uuid description: Unique identifier for the cancellation. status: type: string description: Status of the cancellation request. enum: - pending - confirmed - declined createdOn: type: string format: date-time description: ISO 8601 timestamp when the cancellation was requested. Transfer: type: object description: A money movement operation between two Moov accounts. Transfers have a source (origin) and destination, and are processed over ACH, RTP, or card rails. properties: transferID: type: string format: uuid description: Unique identifier for the transfer. status: type: string description: Current lifecycle status of the transfer. enum: - created - pending - completed - failed - reversed source: $ref: '#/components/schemas/TransferParticipant' destination: $ref: '#/components/schemas/TransferParticipant' amount: $ref: '#/components/schemas/Amount' description: type: string description: Human-readable description of the transfer purpose. metadata: type: object description: Custom key-value pairs for application-specific data. additionalProperties: type: string facilitatorFee: $ref: '#/components/schemas/Amount' moovFee: type: integer description: Moov platform fee in cents. moovFeeDecimal: type: string description: Moov platform fee as a decimal string for precision. createdOn: type: string format: date-time description: ISO 8601 timestamp when the transfer was created. updatedOn: type: string format: date-time description: ISO 8601 timestamp when the transfer was last updated. completedOn: type: string format: date-time description: ISO 8601 timestamp when the transfer completed. Amount: type: object description: A monetary amount with currency denomination. properties: currency: type: string description: ISO 4217 three-letter currency code. default: USD minLength: 3 maxLength: 3 value: type: integer description: Amount in the smallest currency unit (e.g., cents for USD). minimum: 0 CreateTransferRequest: type: object description: Request body for initiating a new transfer between Moov accounts. required: - source - destination - amount properties: source: type: object description: The payment method to debit for this transfer. required: - paymentMethodID properties: paymentMethodID: type: string format: uuid description: The payment method ID to use as the transfer source. cardDetails: type: object description: Additional card-specific options for the source. properties: dynamicDescriptor: type: string description: Custom descriptor shown on card statements. destination: type: object description: The payment method to credit for this transfer. required: - paymentMethodID properties: paymentMethodID: type: string format: uuid description: The payment method ID to use as the transfer destination. amount: $ref: '#/components/schemas/Amount' facilitatorFee: $ref: '#/components/schemas/Amount' description: type: string description: Human-readable description of the transfer purpose. maxLength: 100 metadata: type: object description: Custom key-value pairs for application-specific data. additionalProperties: type: string TransferParticipant: type: object description: Source or destination participant in a Moov transfer. properties: paymentMethodID: type: string format: uuid description: The payment method used for this side of the transfer. paymentMethodType: type: string description: The type of payment method used. enum: - moov-wallet - ach-debit-fund - ach-debit-collect - ach-credit-standard - ach-credit-same-day - rtp-credit - card-payment account: $ref: '#/components/schemas/TransferAccountRef' bankAccount: $ref: '#/components/schemas/BankAccount' wallet: $ref: '#/components/schemas/Wallet' card: $ref: '#/components/schemas/Card' BankAccount: type: object description: A bank account linked to a Moov account as a funding source for ACH and RTP transfers. properties: bankAccountID: type: string format: uuid description: Unique identifier for the bank account. bankName: type: string description: Name of the financial institution. bankAccountType: type: string description: Type of bank account. enum: - checking - savings - loan routingNumber: type: string description: ABA routing transit number for the bank. pattern: ^\d{9}$ lastFourAccountNumber: type: string description: Last four digits of the bank account number. pattern: ^\d{4}$ status: type: string description: Verification and usability status of the bank account. enum: - new - unverified - pending - verified - errored verificationStatus: type: string description: Current state of the bank account verification process. enum: - unverified - pending - verificationFailed - verified - mxVerified createdOn: type: string format: date-time description: ISO 8601 timestamp when the bank account was linked. updatedOn: type: string format: date-time description: ISO 8601 timestamp when the bank account was last updated. parameters: AccountIDParam: name: accountID in: path required: true description: Unique identifier for the Moov account. schema: type: string format: uuid CountParam: name: count in: query description: Maximum number of results to return per page. schema: type: integer minimum: 1 maximum: 100 default: 20 SkipParam: name: skip in: query description: Number of results to skip for pagination. schema: type: integer minimum: 0 default: 0 TransferIDParam: name: transferID in: path required: true description: Unique identifier for the transfer. schema: type: string format: uuid responses: BadRequest: description: The request was malformed or contained invalid parameters. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The requested resource was not found. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Authentication failed. Ensure a valid Bearer token is provided with the required scopes for this operation. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer description: OAuth2 bearer token obtained from the /oauth2/token endpoint. Include in the Authorization header as "Bearer {token}". externalDocs: description: Moov API Documentation url: https://docs.moov.io/api/