> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a withdrawal

> Execute a withdrawal from a virtual account using a previously created quote.

<Warning>
  **Legacy endpoint.** This is part of the legacy withdrawal flow and will be deprecated. An upcoming **Transactions Intent API** will replace it. Avoid building new integrations against this endpoint — contact your Solutions Engineer for migration guidance.
</Warning>


## OpenAPI

````yaml products/retail-va/api-reference/retail-rtd.json POST /v1/users/{userId}/virtual-accounts/{accountId}/withdrawals
openapi: 3.1.0
info:
  title: User Interface API
  description: >-
    API endpoints that are secured with JWT for purposes of calling Meridian
    APIs from a custom user interface.
  version: 1.0.0
servers:
  - url: https://remittances.sandbox.api-us.meridianapps.dev:80
    description: sandbox
security: []
tags: []
externalDocs:
  url: /
paths:
  /v1/users/{userId}/virtual-accounts/{accountId}/withdrawals:
    post:
      tags:
        - Withdrawals
      summary: Create a Withdrawal
      description: >-
        Executes a withdrawal from a virtual account using a previously created
        quote. Deducts the quoted amount from the virtual account balance and
        initiates the payout in local currency to the customer's bank account.
      parameters:
        - name: userId
          in: path
          required: true
          description: ID of the user initiating the withdrawal
          schema:
            type: string
        - name: accountId
          in: path
          required: true
          description: ID of the virtual account to withdraw from
          schema:
            type: string
        - $ref: '#/components/parameters/MeridianApiKeyHeader'
        - $ref: '#/components/parameters/MeridianTimestampHeader'
        - $ref: '#/components/parameters/MeridianSignatureHeader'
      requestBody:
        description: Request body for creating a virtual account withdrawal transaction
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/com.meridianpay.shared.payments.dto.CreateVirtualAccountWithdrawalTransactionRequest
        required: true
      responses:
        '201':
          description: Details of the created transaction
          headers: {}
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/com.meridianpay.remittances.api.dto.CreateVirtualAccountTransactionResponse
        '400':
          description: Invalid request
          headers: {}
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/com.meridianpay.core.common.api.MeridianError
        '401':
          description: Invalid authentication token
          headers: {}
        '404':
          description: No virtual account found
          headers: {}
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/com.meridianpay.core.common.api.MeridianError
        '500':
          description: An internal error occurred
          headers: {}
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/com.meridianpay.core.common.api.MeridianError
      deprecated: true
components:
  parameters:
    MeridianApiKeyHeader:
      name: X-Meridian-Api-Key
      in: header
      required: true
      description: >-
        API key issued by Meridian during provisioning. See
        [Authentication](/products/retail-va/authentication).
      schema:
        type: string
      example: your-api-key
    MeridianTimestampHeader:
      name: X-Meridian-Timestamp
      in: header
      required: true
      description: >-
        Current time in milliseconds since the Unix epoch. Must be within 60
        seconds of the request. See
        [Authentication](/products/retail-va/authentication).
      schema:
        type: string
      example: '1749566400000'
    MeridianSignatureHeader:
      name: X-Meridian-Signature
      in: header
      required: true
      description: >-
        HMAC SHA-256 signature of the canonical request string, computed per
        request. See [Authentication](/products/retail-va/authentication) for
        how to construct it.
      schema:
        type: string
      example: <hmac-sha256-signature>
  schemas:
    com.meridianpay.shared.payments.dto.CreateVirtualAccountWithdrawalTransactionRequest:
      type: object
      properties:
        amount:
          type: number
          description: Amount to withdraw from the virtual account
          example: 50
          title: BigDecimal
        externalRef:
          type:
            - 'null'
            - string
          description: >-
            A unique reference from your own systems used to identify and
            reconcile this transaction, such as a contract number, order ID, or
            internal transaction reference.
          example: order-2026-00142
          title: String
        quoteId:
          type: string
          description: Quote ID for the withdrawal
          example: quote_01HT2P6W9PC2QV4W0Q63QMFJ44
          title: String
      required:
        - amount
        - quoteId
      title: CreateVirtualAccountWithdrawalTransactionRequest
    com.meridianpay.remittances.api.dto.CreateVirtualAccountTransactionResponse:
      type: object
      description: Response returned after creating a withdrawal transaction.
      properties:
        transaction:
          oneOf:
            - type: 'null'
            - $ref: >-
                #/components/schemas/com.meridianpay.remittances.api.dto.VirtualAccountTransactionDto
          description: The created withdrawal transaction
      title: CreateVirtualAccountTransactionResponse
    com.meridianpay.core.common.api.MeridianError:
      type: object
      description: >-
        Standard error response returned when a request cannot be completed.
        Includes a human-readable message and, for validation failures, a list
        of field-level errors.
      properties:
        errorCode:
          type:
            - 'null'
            - string
          description: Machine-readable error code identifying the failure, when available
          title: String
        hasValidationErrors:
          type: boolean
          description: Whether the error includes one or more field-level validation errors
          title: Boolean
        message:
          type: string
          description: Human-readable description of the error
          title: String
        validationErrors:
          type: array
          description: >-
            List of field-level validation errors, empty when the failure is not
            validation-related
          items:
            $ref: >-
              #/components/schemas/com.meridianpay.core.common.api.ValidationError
          title: Array_ValidationError
      required:
        - hasValidationErrors
        - message
        - validationErrors
      title: MeridianError
    com.meridianpay.remittances.api.dto.VirtualAccountTransactionDto:
      type: object
      description: >-
        Details of a virtual account transaction, including amounts, currencies,
        status, and party information.
      properties:
        createdAt:
          type: string
          description: ISO 8601 timestamp when the transaction was created
          title: String
        debitAmount:
          type:
            - 'null'
            - string
          description: >-
            Gross amount debited from the virtual account, in the source
            currency
          example: '50.00'
          title: String
        debitCurrency:
          oneOf:
            - type: 'null'
            - $ref: >-
                #/components/schemas/com.meridianpay.core.common.model.MeridianCurrency
          description: Currency of the debited amount
          example: USD
        depositType:
          type:
            - 'null'
            - string
          description: >-
            Deposit rail used (ACH or WIRE). Present for deposits only; null for
            withdrawals
          title: String
        exchangeRate:
          type:
            - 'null'
            - string
          description: Customer-facing exchange rate applied to the conversion
          example: '56.00'
          title: String
        externalRef:
          type:
            - 'null'
            - string
          description: >-
            The unique reference from your own systems that was supplied when
            the withdrawal was created, used to identify and reconcile this
            transaction.
          example: order-2026-00142
          title: String
        fees:
          type: array
          description: Fees applied to the transaction
          items:
            $ref: >-
              #/components/schemas/com.meridianpay.remittances.api.dto.VirtualAccountTransactionFeeDto
          title: List_VirtualAccountTransactionFeeDto
        fromAmount:
          type:
            - 'null'
            - string
          description: Amount converted, in the source currency
          example: '50.00'
          title: String
        fromCurrency:
          oneOf:
            - type: 'null'
            - $ref: >-
                #/components/schemas/com.meridianpay.core.common.model.MeridianCurrency
          description: Source currency of the conversion
          example: USD
        id:
          type: string
          description: Meridian-generated unique identifier for the transaction
          title: String
        originatorAccount:
          type:
            - 'null'
            - string
          description: Originating account number. Present for deposits only
          title: String
        originatorInstitution:
          type:
            - 'null'
            - string
          description: Originating institution name. Present for deposits only
          title: String
        originatorMemo:
          type:
            - 'null'
            - string
          description: Memo supplied by the originator. Present for deposits only
          title: String
        originatorName:
          type:
            - 'null'
            - string
          description: Originating party name. Present for deposits only
          title: String
        receiverAccount:
          type:
            - 'null'
            - string
          description: Recipient bank account number. Present for withdrawals only
          title: String
        receiverInstitution:
          type:
            - 'null'
            - string
          description: Recipient institution name. Present for withdrawals only
          title: String
        receiverName:
          type:
            - 'null'
            - string
          description: Recipient name. Present for withdrawals only
          title: String
        relatedId:
          type:
            - 'null'
            - string
          description: Identifier of a related transaction or resource, when applicable
          title: String
        relatedIdType:
          oneOf:
            - type: 'null'
            - $ref: >-
                #/components/schemas/com.meridianpay.shared.paymentstransactions.dto.MeridianTransactionRelatedIdType
          description: Type of the related identifier
        status:
          $ref: >-
            #/components/schemas/com.meridianpay.shared.paymentstransactions.dto.VirtualAccountTransactionStatus
          description: Current status of the transaction
        statusReason:
          type:
            - 'null'
            - string
          description: >-
            Reason for the current status, typically present when the
            transaction has failed
          title: String
        toAmount:
          type:
            - 'null'
            - string
          description: Resulting amount, in the destination currency
          example: '2800.00'
          title: String
        toCurrency:
          oneOf:
            - type: 'null'
            - $ref: >-
                #/components/schemas/com.meridianpay.core.common.model.MeridianCurrency
          description: Destination currency of the conversion
          example: PHP
        transactionRef:
          type: string
          description: Partner-displayable transaction reference generated by Meridian
          title: String
        type:
          $ref: >-
            #/components/schemas/com.meridianpay.shared.payments.dto.TransactionDtoType
          description: Type of the transaction
        updatedAt:
          type: string
          description: ISO 8601 timestamp when the transaction was last updated
          title: String
        userId:
          type: string
          description: Meridian identifier of the user the transaction belongs to
          title: String
        virtualAccountId:
          type: string
          description: Identifier of the virtual account involved in the transaction
          title: String
      required:
        - createdAt
        - fees
        - id
        - status
        - transactionRef
        - type
        - updatedAt
        - userId
        - virtualAccountId
      title: VirtualAccountTransactionDto
    com.meridianpay.core.common.api.ValidationError:
      description: >-
        A single validation error describing why a specific field or parameter
        was rejected. Resolves to one of the validation error types below.
      anyOf:
        - $ref: >-
            #/components/schemas/com.meridianpay.core.common.api.ValidationError.InvalidFormat
        - $ref: >-
            #/components/schemas/com.meridianpay.core.common.api.ValidationError.InvalidValue
        - $ref: >-
            #/components/schemas/com.meridianpay.core.common.api.ValidationError.MissingPathParameter
        - $ref: >-
            #/components/schemas/com.meridianpay.core.common.api.ValidationError.MissingQueryParameter
        - $ref: >-
            #/components/schemas/com.meridianpay.core.common.api.ValidationError.MissingRequestBody
        - $ref: >-
            #/components/schemas/com.meridianpay.core.common.api.ValidationError.MissingValue
        - $ref: >-
            #/components/schemas/com.meridianpay.core.common.api.ValidationError.NotFound
        - $ref: >-
            #/components/schemas/com.meridianpay.core.common.api.ValidationError.UnexpectedVerificationError
        - $ref: >-
            #/components/schemas/com.meridianpay.core.common.api.ValidationError.UnprocessableValue
      title: ValidationError
    com.meridianpay.core.common.model.MeridianCurrency:
      type: string
      enum:
        - EUR
        - USD
        - GBP
        - PHP
        - MXN
      title: MeridianCurrency
    com.meridianpay.remittances.api.dto.VirtualAccountTransactionFeeDto:
      type: object
      description: A fee applied to the transaction.
      properties:
        amount:
          type: string
          description: Fee amount, in the fee currency
          example: '5.00'
          title: String
        currency:
          $ref: >-
            #/components/schemas/com.meridianpay.core.common.model.MeridianCurrency
          description: Currency of the fee
          example: USD
        label:
          type: string
          description: Human-readable label describing the fee
          example: Wire processing fee
          title: String
        type:
          $ref: >-
            #/components/schemas/com.meridianpay.shared.payments.dto.TransactionFeeType
          description: Machine-readable fee type identifier
      required:
        - amount
        - currency
        - label
        - type
      title: VirtualAccountTransactionFeeDto
    com.meridianpay.shared.paymentstransactions.dto.MeridianTransactionRelatedIdType:
      type: string
      enum:
        - PAYMENT_LINK
        - TRANSACTION
      title: MeridianTransactionRelatedIdType
    com.meridianpay.shared.paymentstransactions.dto.VirtualAccountTransactionStatus:
      type: string
      enum:
        - PENDING
        - SUCCESS
        - FAILED
        - ERROR
      title: VirtualAccountTransactionStatus
    com.meridianpay.shared.payments.dto.TransactionDtoType:
      type: string
      enum:
        - DEPOSIT
        - WITHDRAWAL
        - AUTOSWEEP
      title: TransactionDtoType
    com.meridianpay.core.common.api.ValidationError.InvalidFormat:
      type: object
      description: >-
        A field was provided in a format the API could not accept, such as a
        malformed date, identifier, or currency code.
      properties:
        fieldRef:
          type: string
          description: Reference to the request field that caused the validation error
          title: String
        message:
          type: string
          description: Human-readable explanation of why the field failed validation
          title: String
      required:
        - fieldRef
        - message
      title: InvalidFormat
    com.meridianpay.core.common.api.ValidationError.InvalidValue:
      type: object
      description: >-
        A field was well-formed but its value failed validation, such as an
        amount that is not positive or a currency code of the wrong length.
      properties:
        fieldRef:
          type: string
          description: Reference to the request field that caused the validation error
          title: String
        message:
          type: string
          description: Human-readable explanation of why the field failed validation
          title: String
      required:
        - fieldRef
        - message
      title: InvalidValue
    com.meridianpay.core.common.api.ValidationError.MissingPathParameter:
      type: object
      description: >-
        A required path parameter was missing from the request URL, such as the
        user or account identifier.
      properties:
        fieldRef:
          type: string
          description: Reference to the request field that caused the validation error
          title: String
        message:
          type: string
          description: Human-readable explanation of why the field failed validation
          title: String
      required:
        - fieldRef
        - message
      title: MissingPathParameter
    com.meridianpay.core.common.api.ValidationError.MissingQueryParameter:
      type: object
      description: A required query parameter was missing from the request.
      properties:
        fieldRef:
          type: string
          description: Reference to the request field that caused the validation error
          title: String
        message:
          type: string
          description: Human-readable explanation of why the field failed validation
          title: String
      required:
        - fieldRef
        - message
      title: MissingQueryParameter
    com.meridianpay.core.common.api.ValidationError.MissingRequestBody:
      type: object
      description: The request body was required but was not provided.
      properties:
        fieldRef:
          type: string
          description: Reference to the request field that caused the validation error
          title: String
        message:
          type: string
          description: Human-readable explanation of why the field failed validation
          title: String
      required:
        - fieldRef
        - message
      title: MissingRequestBody
    com.meridianpay.core.common.api.ValidationError.MissingValue:
      type: object
      description: A required field was missing from the request body.
      properties:
        fieldRef:
          type: string
          description: Reference to the request field that caused the validation error
          title: String
        message:
          type: string
          description: Human-readable explanation of why the field failed validation
          title: String
      required:
        - fieldRef
        - message
      title: MissingValue
    com.meridianpay.core.common.api.ValidationError.NotFound:
      type: object
      description: >-
        A resource referenced by the request could not be found, such as an
        unknown quote or virtual account.
      properties:
        fieldRef:
          type: string
          description: Reference to the request field that caused the validation error
          title: String
        message:
          type: string
          description: Human-readable explanation of why the field failed validation
          title: String
      required:
        - fieldRef
        - message
      title: NotFound
    com.meridianpay.core.common.api.ValidationError.UnexpectedVerificationError:
      type: object
      description: An unexpected error occurred while verifying the request.
      properties:
        fieldRef:
          type: string
          description: Reference to the request field that caused the validation error
          title: String
        message:
          type: string
          description: Human-readable explanation of why the field failed validation
          title: String
      required:
        - fieldRef
        - message
      title: UnexpectedVerificationError
    com.meridianpay.core.common.api.ValidationError.UnprocessableValue:
      type: object
      description: >-
        A field value was well-formed but could not be processed in the current
        context, such as a quote that has expired.
      properties:
        fieldRef:
          type: string
          description: Reference to the request field that caused the validation error
          title: String
        message:
          type: string
          description: Human-readable explanation of why the field failed validation
          title: String
      required:
        - fieldRef
        - message
      title: UnprocessableValue
    com.meridianpay.shared.payments.dto.TransactionFeeType:
      type: string
      enum:
        - WIRE_PROCESSING_FEE
      title: TransactionFeeType

````