> ## 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 Session > Create a Virtual Account Session to launch the hosted Meridian onboarding experience. ## OpenAPI ````yaml products/retail-va/api-reference/retail-rtd.json POST /v1/virtual-accounts/sessions 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/virtual-accounts/sessions: post: tags: - Sessions summary: Create a Virtual Account Session description: >- Validates customer and wallet payload and, upon successful validation, returns a session key that can be used to start the hosted Meridian onboarding experience. parameters: - $ref: '#/components/parameters/MeridianApiKeyHeader' - $ref: '#/components/parameters/MeridianTimestampHeader' - $ref: '#/components/parameters/MeridianSignatureHeader' requestBody: description: Request body to create a Virtual Account Session content: application/json: schema: $ref: >- #/components/schemas/com.meridianpay.remittances.api.dto.virtualaccount.VirtualAccountCreateSessionRequest required: true responses: '201': description: Created the session and stored the contents for later use headers: {} content: application/json: schema: $ref: >- #/components/schemas/com.meridianpay.remittances.api.dto.virtualaccount.VirtualAccountCreateSessionResponse '400': description: Malformed or invalid submission. headers: {} content: application/json: schema: $ref: >- #/components/schemas/com.meridianpay.core.common.api.MeridianError '401': description: Invalid authentication token headers: {} '500': description: Internal Server Error headers: {} deprecated: false 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: schemas: com.meridianpay.remittances.api.dto.virtualaccount.VirtualAccountCreateSessionRequest: type: object properties: customer: oneOf: - type: 'null' - $ref: >- #/components/schemas/com.meridianpay.remittances.api.dto.virtualaccount.KYC customerId: type: string description: >- A non-sensitive string that uniquely identifies your customer across all Meridian sessions. Must be consistent and never change — Meridian uses this to detect whether to route a customer to onboarding or Account Home. Note: this value is case-sensitive; inconsistent casing will cause a returning customer to be treated as new. title: String receiver: $ref: >- #/components/schemas/com.meridianpay.remittances.api.dto.virtualaccount.Receiver redirectUrl: type: string description: Deep Link or Universal Link to bring the user back to your app title: String required: - customer - customerId - receiver - redirectUrl title: VirtualAccountCreateSessionRequest com.meridianpay.remittances.api.dto.virtualaccount.VirtualAccountCreateSessionResponse: type: object properties: expiresAt: type: string description: ISO8601 datetime string for the expiration of the session title: String sessionKey: type: string description: Unique session key assigned to this transaction payload title: String required: - expiresAt - sessionKey title: VirtualAccountCreateSessionResponse 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.virtualaccount.KYC: type: object description: >- All fields in this data structure should be populated on a best-efforts basis. No field is required but this data helps to provide a seamless user experience for the customer so that they don’t need to re-enter information already provided to the partner. properties: addressLine1: type: - 'null' - string description: Customer residential address title: String addressLine2: type: - 'null' - string description: Customer residential address title: String city: type: - 'null' - string description: Customer residential address title: String countryCode: type: - 'null' - string description: 2-character country code title: String dateOfBirth: type: - 'null' - string description: YYYY-MM-DD date format title: String email: type: - 'null' - string description: Email address title: String employmentStatus: type: - 'null' - string description: Employment status title: String employmentStatusDescription: type: - 'null' - string description: Custom option for OTHER title: String firstName: type: - 'null' - string description: Customer legal name title: String lastName: type: - 'null' - string description: Customer legal name title: String monthlyDepositVolume: type: - 'null' - string description: Expected monthly deposit volume title: String monthlyDepositVolumeCurrency: type: - 'null' - string description: Currency for expected monthly deposit volume title: String occupation: type: - 'null' - string description: User Occupation title: String phoneNumber: type: - 'null' - string description: E.164 formatted phone number title: String postalCode: type: - 'null' - string description: Customer residential address title: String primarySourceOfFunds: type: - 'null' - string description: User primary source of funds title: String primarySourceOfFundsDescription: type: - 'null' - string description: Custom option for OTHER title: String stateProvince: type: - 'null' - string description: Customer residential address title: String title: KYC com.meridianpay.remittances.api.dto.virtualaccount.Receiver: type: object description: >- This data is separate from KYC information, as this will not be changed by the customer during onboarding. All details provided here must match the information associated with the receiver of funds withdrawn from the virtual account. properties: firstName: type: string description: First name of the receiver title: String lastName: type: string description: Last name of the receiver title: String phoneNumber: type: string description: E.164 formatted phone number title: String linkedAccount: $ref: >- #/components/schemas/com.meridianpay.remittances.api.dto.virtualaccount.LinkedAccount required: - firstName - lastName - phoneNumber - linkedAccount title: Receiver 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.remittances.api.dto.virtualaccount.LinkedAccount: type: object properties: type: type: string enum: - BLOCKCHAIN - WALLET - BANKACCOUNT description: Type of linked account title: String blockchain: oneOf: - type: 'null' - $ref: >- #/components/schemas/com.meridianpay.remittances.api.dto.virtualaccount.BlockchainAccount wallet: oneOf: - type: 'null' - $ref: >- #/components/schemas/com.meridianpay.remittances.api.dto.virtualaccount.WalletAccount bankAccount: oneOf: - type: 'null' - $ref: >- #/components/schemas/com.meridianpay.remittances.api.dto.virtualaccount.BankAccount required: - type title: LinkedAccount 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.remittances.api.dto.virtualaccount.BlockchainAccount: type: object properties: chainId: type: string description: Chain ID from chainlist.org title: String address: type: string description: Wallet address title: String required: - chainId - address title: BlockchainAccount com.meridianpay.remittances.api.dto.virtualaccount.WalletAccount: type: object properties: walletId: type: string description: Internal wallet identifier for Fintech wallet title: String required: - walletId title: WalletAccount com.meridianpay.remittances.api.dto.virtualaccount.BankAccount: type: object properties: accountNumber: type: string description: Bank account number title: String accountName: type: - 'null' - string description: Friendly name for the account title: String accountType: oneOf: - type: 'null' - type: string enum: - CHECKING - SAVINGS description: Type of bank account title: String required: - accountNumber title: BankAccount ````