> ## 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 transaction intent > Creates a transaction-shaped preview from debit and credit payment instruments. No funds movement occurs until the intent is committed. ## OpenAPI ````yaml /products/meridian-accounts/api-reference/meridian-accounts.json post /v1/transaction-intents openapi: 3.1.1 info: title: Meridian API version: '1.0' description: API documentation for Meridian services contact: name: Meridian url: https://mnai.com email: support@mnai.com license: name: Proprietary url: https://mnai.com servers: - url: https://sandbox-api.va.meridianpay.com description: Sandbox - url: https://api.va.mnai.com description: Production security: [] paths: /v1/transaction-intents: post: tags: - Transaction Intents summary: Create a transaction intent description: >- Creates a transaction-shaped preview from debit and credit payment instruments. No funds movement occurs until the intent is committed. operationId: createTransactionIntent parameters: - name: Authorization in: header description: >- Bearer authentication header of the form `Bearer {token}`. Required for client-server (JWT) authentication. See [Authentication](/products/meridian-accounts/guides/authentication-overview). schema: type: string - name: X-Meridian-Program-Id in: header description: >- Identifies the program context for the request. Required for server-to-server (HMAC) authentication. See [Authentication](/products/meridian-accounts/guides/authentication-overview). schema: type: string - name: X-Meridian-User-Id in: header description: >- Identifies the Meridian user targeted by the request. Required for server-to-server (HMAC) authentication with MULTI_USER integrations; omit for SINGLE_USER. See [Authentication](/products/meridian-accounts/guides/authentication-overview). schema: type: string - name: X-Meridian-Api-Key in: header description: >- Partner API key issued by Meridian during provisioning. Required for server-to-server (HMAC) authentication. See [Authentication](/products/meridian-accounts/guides/authentication-overview). schema: type: string - name: X-Meridian-Timestamp in: header description: >- Current time in milliseconds since the Unix epoch. Must be within 60 seconds of the request. Required for server-to-server (HMAC) authentication. See [Authentication](/products/meridian-accounts/guides/authentication-overview). schema: type: string - name: X-Meridian-Signature in: header description: >- HMAC SHA-256 signature of the canonical request string, computed per request. Required for server-to-server (HMAC) authentication. See [Authentication](/products/meridian-accounts/guides/authentication-overview) for how to construct it. schema: type: string responses: '201': description: The created transaction intent preview content: application/json: schema: $ref: '#/components/schemas/MeridianTransactionIntentDto' '400': description: Invalid transaction intent request content: application/json: schema: $ref: '#/components/schemas/MeridianError' '401': description: Missing or invalid authentication content: application/json: schema: $ref: '#/components/schemas/MeridianError' '403': description: >- The authenticated account does not have the required scope or instrument access content: application/json: schema: $ref: '#/components/schemas/MeridianError' '500': description: Unexpected error while processing the transaction intent request content: application/json: schema: $ref: '#/components/schemas/MeridianError' security: - meridian-account-jwt: [] - partner-api-key: [] components: schemas: MeridianTransactionIntentDto: type: object title: MeridianTransactionIntentDto required: - id - type - createdAt - updatedAt - status - debitAmount - debitCurrency - debitInstrument - creditAmount - creditCurrency - creditInstrument - fees - exchangeRate properties: id: type: string type: type: string enum: - TRANSFER - DEPOSIT - WITHDRAWAL - REFUND - PARTIAL_REFUND createdAt: type: string format: date-time updatedAt: type: string format: date-time status: type: string enum: - CREATED - EXPIRED - CANCELED - COMMITTED - FAILED statusReason: type: - string - 'null' relatedTransactionId: type: - string - 'null' debitAmount: type: string debitCurrency: type: string debitMemo: type: - string - 'null' debitInstrument: $ref: '#/components/schemas/Transaction Instrument' creditAmount: type: string creditCurrency: type: string creditInstrument: $ref: '#/components/schemas/Transaction Instrument' fees: type: array items: $ref: '#/components/schemas/Transaction Fee' exchangeRate: type: string purpose: type: - string - 'null' enum: - PAYMENT_FOR_SERVICES - PAYMENT_FOR_SOFTWARE - PAYMENT_FOR_IMPORTED_GOODS - TRAVEL_SERVICES - VENDOR_CONTRACTOR_PAYOUTS - TRANSFER_TO_OWN_ACCOUNT - INVESTMENT_IN_SHARES - PURCHASE_OF_PROPERTY - REPAYMENT_OF_LOANS - SALARY - PAYMENT_OF_PROPERTY_RENTAL - INFORMATION_SERVICE_CHARGES - ADVERTISING_AND_PUBLIC_RELATIONS_EXPENSES - ROYALTY_TRADEMARK_PATENT_AND_COPYRIGHT_FEES - BROKER_FRONTEND_GUARANTEE_AND_CUSTODIAN_FEES - ADVISOR_TECHNICAL_AND_ACADEMIC_FEES - REPRESENTATIVE_OFFICE_EXPENSES - TAX_PAYMENT - TRANSPORTATION_FEES_FOR_GOODS - CONSTRUCTION_COSTS - INSURANCE_PREMIUM - GENERAL_GOODS_TRADES_OFFLINE - INSURANCE_CLAIMS_PAYMENT - FAMILY_MAINTENANCE - EDUCATION_RELATED_EXPENSES - MEDICAL_TREATMENT - DONATIONS - MUTUAL_FUND_INVESTMENT - CURRENCY_EXCHANGE - USER_WITHDRAWAL - ADVANCE_PAYMENTS_FOR_GOODS - VENDOR_CONTRACTOR_PAYOUTS_SOFTWARE_DEVELOPMENT - MERCHANT_SETTLEMENT - REPATRIATION_FUND_SETTLEMENT - PERSONAL_REMITTANCE - RETURN_OF_FUNDS MeridianError: type: object title: MeridianError description: >- Represents an error response from the Meridian API, including validation errors and an optional error code. required: - message properties: validationErrors: type: array description: >- An array of validation errors that occurred during the processing of the request. This field is optional and may be empty if there are no validation errors. items: $ref: '#/components/schemas/ValidationError' errorCode: type: string description: >- Machine-readable code identifying the failure. Absent when the failure is fully described by `validationErrors`. Clients should tolerate codes added in the future. enum: - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - INVALID_REQUEST - INTERNAL_ERROR - INVALID_USER_TYPE - SINGLE_USER_KEY_NOT_ALLOWED - USER_ID_HEADER_REQUIRED - USER_ID_HEADER_NOT_ALLOWED message: type: string description: >- A human-readable message describing the error. This field is required and should provide a clear explanation of the error that occurred. Transaction Instrument: type: object title: Transaction Instrument description: Payment instrument involved in the transaction oneOf: - $ref: '#/components/schemas/Account Instrument' - $ref: '#/components/schemas/Bank Account Instrument' - $ref: '#/components/schemas/External Wallet Instrument' - $ref: '#/components/schemas/Virtual Account Instrument' discriminator: propertyName: instrumentType mapping: ACCOUNT: $ref: '#/components/schemas/Account Instrument' BANK_ACCOUNT: $ref: '#/components/schemas/Bank Account Instrument' VIRTUAL_ACCOUNT: $ref: '#/components/schemas/Virtual Account Instrument' EXTERNAL_WALLET: $ref: '#/components/schemas/External Wallet Instrument' Transaction Fee: type: object title: Transaction Fee description: Fee applied to a transaction required: - type - label - amount - currency properties: type: type: string description: Fee type example: PROCESSING label: type: string description: Human-readable label for the fee example: Processing fee amount: type: string description: Fee amount as a decimal string example: '1.00' currency: type: string description: ISO 4217 currency code example: USD ValidationError: type: object title: ValidationError description: >- Represents a validation error that occurred during the processing of a request to the Meridian API. One of the following types of validation errors may be present: InvalidFormat, InvalidValue, MissingValue, UnprocessableValue, UnexpectedVerificationError, MissingRequestBody, MissingPathParameter, MissingQueryParameter, or NotFound. Each validation error includes a reference to the field that caused the error and a message describing the error. oneOf: - $ref: '#/components/schemas/InvalidFormat' - $ref: '#/components/schemas/InvalidValue' - $ref: '#/components/schemas/MissingPathParameter' - $ref: '#/components/schemas/MissingQueryParameter' - $ref: '#/components/schemas/MissingRequestBody' - $ref: '#/components/schemas/MissingValue' - $ref: '#/components/schemas/NotFound' - $ref: '#/components/schemas/UnexpectedVerificationError' - $ref: '#/components/schemas/Unknown' - $ref: '#/components/schemas/UnprocessableValue' discriminator: propertyName: type mapping: InvalidFormat: $ref: '#/components/schemas/InvalidFormat' InvalidValue: $ref: '#/components/schemas/InvalidValue' MissingPathParameter: $ref: '#/components/schemas/MissingPathParameter' MissingQueryParameter: $ref: '#/components/schemas/MissingQueryParameter' MissingRequestBody: $ref: '#/components/schemas/MissingRequestBody' MissingValue: $ref: '#/components/schemas/MissingValue' NotFound: $ref: '#/components/schemas/NotFound' UnexpectedVerificationError: $ref: '#/components/schemas/UnexpectedVerificationError' Unknown: $ref: '#/components/schemas/Unknown' UnprocessableValue: $ref: '#/components/schemas/UnprocessableValue' Account Instrument: type: object title: Account Instrument description: Meridian (balance) account instrument required: - account properties: account: $ref: '#/components/schemas/Account Instrument Details' instrumentType: type: string description: Instrument type example: ACCOUNT enum: - ACCOUNT - BANK_ACCOUNT - VIRTUAL_ACCOUNT - EXTERNAL_WALLET Bank Account Instrument: type: object title: Bank Account Instrument description: Bank account instrument required: - bankAccount properties: bankAccount: $ref: '#/components/schemas/Bank Account Instrument Details' instrumentType: type: string description: Instrument type example: BANK_ACCOUNT enum: - ACCOUNT - BANK_ACCOUNT - VIRTUAL_ACCOUNT - EXTERNAL_WALLET External Wallet Instrument: type: object title: External Wallet Instrument description: External wallet instrument required: - externalWallet properties: externalWallet: $ref: '#/components/schemas/External Wallet Instrument Details' instrumentType: type: string description: Instrument type example: EXTERNAL_WALLET enum: - ACCOUNT - BANK_ACCOUNT - VIRTUAL_ACCOUNT - EXTERNAL_WALLET Virtual Account Instrument: type: object title: Virtual Account Instrument description: Virtual account instrument required: - virtualAccount properties: virtualAccount: $ref: '#/components/schemas/Virtual Account Instrument Details' instrumentType: type: string description: Instrument type example: VIRTUAL_ACCOUNT enum: - ACCOUNT - BANK_ACCOUNT - VIRTUAL_ACCOUNT - EXTERNAL_WALLET InvalidFormat: type: object title: InvalidFormat description: The provided value exists, but its format is invalid for the field. required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. InvalidValue: type: object title: InvalidValue description: >- The provided value is syntactically valid, but not accepted for the field. required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. MissingPathParameter: type: object title: MissingPathParameter description: A required path parameter was not supplied. required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. MissingQueryParameter: type: object title: MissingQueryParameter description: A required query parameter was not supplied. required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. MissingRequestBody: type: object title: MissingRequestBody description: >- The request body is missing or does not contain the required non-null fields. properties: message: type: string description: A human-readable explanation of the validation failure. fieldRef: type: string description: The field or parameter that triggered the validation error. MissingValue: type: object title: MissingValue description: A required value for the field was not provided. required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. NotFound: type: object title: NotFound description: The referenced principal object was not found. required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. UnexpectedVerificationError: type: object title: UnexpectedVerificationError description: A downstream verification step failed while checking the value. required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. Unknown: type: object title: Unknown description: >- A validation error occurred but the specific field could not be determined. properties: message: type: string description: A human-readable explanation of the validation failure. fieldRef: type: string description: The field or parameter that triggered the validation error. UnprocessableValue: type: object title: UnprocessableValue description: The provided value cannot be processed into a valid result. required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. Account Instrument Details: type: object title: Account Instrument Details description: Meridian (balance) account details required: - id - displayName - currency properties: id: type: string description: Unique identifier of the account example: acc_01JMEROAK7421 displayName: type: string description: Display name of the account example: Oak Street Purchase Contract currency: type: string description: Currency of the account example: USD Bank Account Instrument Details: type: object title: Bank Account Instrument Details description: Bank account details required: - id - displayName - currency - mask properties: id: type: string description: Unique identifier of the bank account example: ba_01JMERPHSETTLE01 displayName: type: string description: Display name of the bank account example: PHP Settlement Account currency: type: string description: Currency of the bank account example: PHP mask: type: string description: Masked account identifier example: '****4321' External Wallet Instrument Details: type: object title: External Wallet Instrument Details description: External wallet details required: - id - displayName - currency - mask properties: id: type: string description: Unique identifier of the external wallet example: pi_extwlt_treasury displayName: type: string description: Display name of the external wallet example: Ethereum Treasury Wallet currency: type: string description: Currency of the external wallet example: USDC_ETH mask: type: string description: Masked account identifier example: '****1234' Virtual Account Instrument Details: type: object title: Virtual Account Instrument Details description: Virtual account details required: - id - displayName - currency - mask properties: id: type: string description: Unique identifier of the virtual account example: va_01JMERVA0002 displayName: type: string description: Display name of the virtual account example: USD Virtual Account currency: type: string description: Currency of the virtual account example: USD mask: type: string description: Masked account identifier example: '****0002' ````