> ## 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 Beneficiary

> Creates a beneficiary together with its first payout instrument for the authenticated Meridian account. The instrument is either a bank account (`BANK_ACCOUNT`) or a stablecoin wallet address (`BLOCKCHAIN_WALLET`); further instruments are attached with `POST /v1/beneficiaries/{beneficiaryId}/instruments`.



## OpenAPI

````yaml /products/meridian-accounts/api-reference/meridian-accounts.json post /v1/beneficiaries
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/beneficiaries:
    post:
      tags:
        - Beneficiaries
      summary: Create a Beneficiary
      description: >-
        Creates a beneficiary together with its first payout instrument for the
        authenticated Meridian account. The instrument is either a bank account
        (`BANK_ACCOUNT`) or a stablecoin wallet address (`BLOCKCHAIN_WALLET`);
        further instruments are attached with `POST
        /v1/beneficiaries/{beneficiaryId}/instruments`.
      operationId: createBeneficiary
      parameters:
        - name: X-Meridian-Api-Key
          in: header
          description: >-
            Server-to-server (HMAC) requests only. Partner API key issued by
            Meridian during provisioning.
          schema:
            type: string
          example: your-api-key
        - name: X-Meridian-Timestamp
          in: header
          description: >-
            Server-to-server (HMAC) requests only. Current time in milliseconds
            since the Unix epoch. Must be within 60 seconds of the request.
          schema:
            type: string
          example: '1749566400000'
        - name: X-Meridian-Program-Id
          in: header
          description: >-
            Server-to-server (HMAC) requests only. Identifies the program
            context for the request.
          schema:
            type: string
          example: your-program-id
        - name: X-Meridian-User-Id
          in: header
          description: >-
            Server-to-server (HMAC) requests only. Identifies the Meridian user
            targeted by the request. Required for MULTI_USER integrations; omit
            for SINGLE_USER.
          schema:
            type: string
          example: user_123
      requestBody:
        description: Beneficiary identity and first payout instrument
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBeneficiaryRequest'
            examples:
              business_stablecoin_wallet:
                $ref: '#/components/examples/CreateBeneficiaryRequestBusinessWallet'
              self_stablecoin_wallet:
                $ref: '#/components/examples/CreateBeneficiaryRequestSelfWallet'
              person_us_bank_account:
                $ref: >-
                  #/components/examples/CreateBeneficiaryRequestPersonUsBankAccount
              business_swift_bank_account:
                $ref: '#/components/examples/CreateBeneficiaryRequestBusinessSwift'
        required: true
      responses:
        '201':
          description: The newly created beneficiary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Beneficiary'
              examples:
                business_with_wallet:
                  $ref: '#/components/examples/CreateBeneficiaryBusinessWithWallet'
                person_with_bank_account:
                  $ref: '#/components/examples/CreateBeneficiaryPersonWithBankAccount'
        '400':
          description: Invalid or malformed request body
          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 caller is not permitted: JWT scope missing, or the
            partner API key lacks entitlement, user ownership, or user-type
            match
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeridianError'
        '409':
          description: >-
            The wallet address is already registered as a payout destination for
            a different beneficiary of this account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeridianError'
        '503':
          description: >-
            A downstream provider was unreachable. The request was not applied
            and may be retried with the same idempotency key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeridianError'
      security:
        - meridian-account-jwt: []
        - partner-api-key: []
components:
  schemas:
    CreateBeneficiaryRequest:
      type: object
      title: Create Beneficiary Request
      description: >-
        A beneficiary to create together with its first payout instrument.
        `type` selects the variant: `PERSON` or `BUSINESS`.
      required:
        - type
      properties:
        type:
          type: string
          description: Beneficiary type discriminator
          enum:
            - PERSON
            - BUSINESS
      discriminator:
        propertyName: type
        mapping:
          PERSON:
            $ref: '#/components/schemas/CreatePersonBeneficiaryRequest'
          BUSINESS:
            $ref: '#/components/schemas/CreateBusinessBeneficiaryRequest'
    Beneficiary:
      type: object
      title: Beneficiary
      description: >-
        A beneficiary registered for the authenticated Meridian account. `type`
        selects the variant: `PERSON` or `BUSINESS`.
      required:
        - type
      properties:
        type:
          type: string
          description: Beneficiary type discriminator
          enum:
            - PERSON
            - BUSINESS
      discriminator:
        propertyName: type
        mapping:
          PERSON:
            $ref: '#/components/schemas/PersonBeneficiaryResponse'
          BUSINESS:
            $ref: '#/components/schemas/BusinessBeneficiaryResponse'
    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
            - INFORMATION_REQUEST_NOT_EDITABLE
            - INVALID_USER_TYPE
            - SINGLE_USER_KEY_NOT_ALLOWED
            - USER_ID_HEADER_REQUIRED
            - USER_ID_HEADER_NOT_ALLOWED
            - PDF_PAGE_LIMIT_EXCEEDED
            - PDF_PASSWORD_PROTECTED
            - PDF_UNREADABLE
        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.
    CreatePersonBeneficiaryRequest:
      title: Create Person Beneficiary Request
      description: Create a person beneficiary together with its first instrument
      allOf:
        - $ref: '#/components/schemas/CreateBeneficiaryRequest'
        - type: object
          required:
            - firstName
            - lastName
            - address
            - instrument
          properties:
            firstName:
              type: string
              description: First name
              example: Sherlock
            lastName:
              type: string
              description: Last name
              example: Holmes
            address:
              $ref: '#/components/schemas/BeneficiaryAddress'
            instrument:
              $ref: '#/components/schemas/CreateBeneficiaryInstrumentRequest'
            dateOfBirth:
              type:
                - string
                - 'null'
              description: Date of birth
              example: '1854-01-06'
              format: date
            displayName:
              type:
                - string
                - 'null'
              description: Human-readable display name for the beneficiary
              example: Sherlock Holmes
            email:
              type:
                - string
                - 'null'
              description: Email address
            phoneNumber:
              type:
                - string
                - 'null'
              description: Phone number
            phoneCountry:
              type:
                - string
                - 'null'
              description: ISO 3166-1 alpha-2 country code of the phone number
              example: GB
            relationshipToUser:
              type:
                - string
                - 'null'
              description: Beneficiary's relationship to the account owner
              example: THIRD_PARTY
              enum:
                - SELF
                - THIRD_PARTY
                - null
    CreateBusinessBeneficiaryRequest:
      title: Create Business Beneficiary Request
      description: Create a business beneficiary together with its first instrument
      allOf:
        - $ref: '#/components/schemas/CreateBeneficiaryRequest'
        - type: object
          required:
            - name
            - address
            - instrument
          properties:
            name:
              type: string
              description: Legal name of the business
              example: Baker Street Ltd
            address:
              $ref: '#/components/schemas/BeneficiaryAddress'
            instrument:
              $ref: '#/components/schemas/CreateBeneficiaryInstrumentRequest'
            displayName:
              type:
                - string
                - 'null'
              description: Human-readable display name for the beneficiary
              example: Baker Street Ltd
            email:
              type:
                - string
                - 'null'
              description: Email address
            phoneNumber:
              type:
                - string
                - 'null'
              description: Phone number
            phoneCountry:
              type:
                - string
                - 'null'
              description: ISO 3166-1 alpha-2 country code of the phone number
              example: GB
            relationshipToUser:
              type:
                - string
                - 'null'
              description: Beneficiary's relationship to the account owner
              example: THIRD_PARTY
              enum:
                - SELF
                - THIRD_PARTY
                - null
    PersonBeneficiaryResponse:
      title: Person Beneficiary Response
      description: A person beneficiary
      allOf:
        - $ref: '#/components/schemas/Beneficiary'
        - type: object
          required:
            - id
            - counterpartyId
            - createdAt
            - updatedAt
          properties:
            id:
              type: string
              description: Unique identifier of the beneficiary
              example: uscp-01JMERBENEF001
            counterpartyId:
              type: string
              description: Identifier of the underlying counterparty
              example: uscp-01JMERBENEF001
            createdAt:
              type: string
              description: Timestamp when the beneficiary was created
              example: '2026-04-30T14:00:00Z'
              format: date-time
            updatedAt:
              type: string
              description: Timestamp when the beneficiary was last updated
              example: '2026-04-30T14:00:00Z'
              format: date-time
            firstName:
              type:
                - string
                - 'null'
              description: First name of the beneficiary
            lastName:
              type:
                - string
                - 'null'
              description: Last name of the beneficiary
            dateOfBirth:
              type:
                - string
                - 'null'
              description: Date of birth of the beneficiary
              format: date
            displayName:
              type:
                - string
                - 'null'
              description: Display name of the beneficiary
            email:
              type:
                - string
                - 'null'
              description: Email address of the beneficiary
            phoneNumber:
              type:
                - string
                - 'null'
              description: Phone number of the beneficiary
            address:
              oneOf:
                - $ref: '#/components/schemas/BeneficiaryAddress'
                - type: 'null'
            relationshipToUser:
              type:
                - string
                - 'null'
              description: Beneficiary's relationship to the account owner
              example: THIRD_PARTY
              enum:
                - SELF
                - THIRD_PARTY
                - null
    BusinessBeneficiaryResponse:
      title: Business Beneficiary Response
      description: A business beneficiary
      allOf:
        - $ref: '#/components/schemas/Beneficiary'
        - type: object
          required:
            - id
            - counterpartyId
            - createdAt
            - updatedAt
          properties:
            id:
              type: string
              description: Unique identifier of the beneficiary
              example: uscp-01JMERBENEF001
            counterpartyId:
              type: string
              description: Identifier of the underlying counterparty
              example: uscp-01JMERBENEF001
            createdAt:
              type: string
              description: Timestamp when the beneficiary was created
              example: '2026-04-30T14:00:00Z'
              format: date-time
            updatedAt:
              type: string
              description: Timestamp when the beneficiary was last updated
              example: '2026-04-30T14:00:00Z'
              format: date-time
            name:
              type:
                - string
                - 'null'
              description: Legal name of the beneficiary
            displayName:
              type:
                - string
                - 'null'
              description: Display name of the beneficiary
            email:
              type:
                - string
                - 'null'
              description: Email address of the beneficiary
            phoneNumber:
              type:
                - string
                - 'null'
              description: Phone number of the beneficiary
            address:
              oneOf:
                - $ref: '#/components/schemas/BeneficiaryAddress'
                - type: 'null'
            relationshipToUser:
              type:
                - string
                - 'null'
              description: Beneficiary's relationship to the account owner
              example: THIRD_PARTY
              enum:
                - SELF
                - THIRD_PARTY
                - null
    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.
      required:
        - type
      properties:
        type:
          type: string
          description: Identifies which ValidationError this is.
          enum:
            - InvalidFormat
            - InvalidValue
            - MissingPathParameter
            - MissingQueryParameter
            - MissingRequestBody
            - MissingValue
            - NotFound
            - UnexpectedVerificationError
            - Unknown
            - 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'
    BeneficiaryAddress:
      type: object
      title: Beneficiary Address
      description: >-
        Address of the beneficiary's bank. Required by RouteFusion for non-US
        bank countries; a missing field is reported as a field-level validation
        error on submission.
      required:
        - addressLine1
        - city
        - postalCode
        - countryCode
      properties:
        addressLine1:
          type: string
          description: First line of the address
          example: 221B Baker Street
        city:
          type: string
          description: City
          example: London
        postalCode:
          type: string
          description: Postal or ZIP code
          example: NW1 6XE
        countryCode:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: GB
        addressLine2:
          type:
            - string
            - 'null'
          description: Second line of the address
        stateProvince:
          type:
            - string
            - 'null'
          description: State or province
    CreateBeneficiaryInstrumentRequest:
      type: object
      title: Create Beneficiary Instrument Request
      description: >-
        A payout instrument to register for a beneficiary. `type` selects the
        variant: `BANK_ACCOUNT` for a bank account, `BLOCKCHAIN_WALLET` for a
        stablecoin wallet address.
      required:
        - type
      properties:
        type:
          type: string
          description: Instrument type discriminator
          enum:
            - BANK_ACCOUNT
            - EWALLET
            - BLOCKCHAIN_WALLET
      discriminator:
        propertyName: type
        mapping:
          BANK_ACCOUNT:
            $ref: '#/components/schemas/BankAccountInstrumentRequest'
          BLOCKCHAIN_WALLET:
            $ref: '#/components/schemas/WalletInstrumentRequest'
    InvalidFormat:
      title: InvalidFormat
      description: The provided value exists, but its format is invalid for the field.
      allOf:
        - $ref: '#/components/schemas/ValidationError'
        - type: object
          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:
      title: InvalidValue
      description: >-
        The provided value is syntactically valid, but not accepted for the
        field.
      allOf:
        - $ref: '#/components/schemas/ValidationError'
        - type: object
          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:
      title: MissingPathParameter
      description: A required path parameter was not supplied.
      allOf:
        - $ref: '#/components/schemas/ValidationError'
        - type: object
          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:
      title: MissingQueryParameter
      description: A required query parameter was not supplied.
      allOf:
        - $ref: '#/components/schemas/ValidationError'
        - type: object
          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:
      title: MissingRequestBody
      description: >-
        The request body is missing or does not contain the required non-null
        fields.
      allOf:
        - $ref: '#/components/schemas/ValidationError'
        - type: object
          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:
      title: MissingValue
      description: A required value for the field was not provided.
      allOf:
        - $ref: '#/components/schemas/ValidationError'
        - type: object
          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:
      title: NotFound
      description: The referenced principal object was not found.
      allOf:
        - $ref: '#/components/schemas/ValidationError'
        - type: object
          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:
      title: UnexpectedVerificationError
      description: A downstream verification step failed while checking the value.
      allOf:
        - $ref: '#/components/schemas/ValidationError'
        - type: object
          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:
      title: Unknown
      description: >-
        A validation error occurred but the specific field could not be
        determined.
      allOf:
        - $ref: '#/components/schemas/ValidationError'
        - type: object
          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:
      title: UnprocessableValue
      description: The provided value cannot be processed into a valid result.
      allOf:
        - $ref: '#/components/schemas/ValidationError'
        - type: object
          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.
    BankAccountInstrumentRequest:
      title: Bank Account Instrument Request
      description: Bank account instrument to create for a beneficiary
      allOf:
        - $ref: '#/components/schemas/CreateBeneficiaryInstrumentRequest'
        - type: object
          required:
            - bankAccount
            - idempotencyKey
          properties:
            bankAccount:
              $ref: '#/components/schemas/BeneficiaryBankAccountInput'
            idempotencyKey:
              type: string
              description: >-
                Client-supplied idempotency key; retries with the same key are
                de-duplicated
              example: a1b2c3d4-1111-2222-3333-444455556666
    WalletInstrumentRequest:
      title: Wallet Instrument Request
      description: Blockchain wallet instrument to create for a beneficiary
      allOf:
        - $ref: '#/components/schemas/CreateBeneficiaryInstrumentRequest'
        - type: object
          required:
            - displayName
            - walletAddress
            - currency
            - idempotencyKey
          properties:
            displayName:
              type: string
              description: Display label for the wallet
              example: Treasury unmanaged wallet D
            walletAddress:
              type: string
              description: Beneficiary's on-chain wallet address
              example: '0x9f8B4a71Cc0Ed2b3F6a9E7c1D5b8A2f4E6c04C21'
            currency:
              type: string
              description: >-
                Stablecoin currency of the destination. One of USDC_ETH,
                USDT_ETH, USDC_BASE, USDT_BASE, USDC_POLY, USDT_POLY. The
                network is derived from this value.
              example: USDC_ETH
            idempotencyKey:
              type: string
              description: >-
                Client-supplied idempotency key; retries with the same key are
                de-duplicated
              example: a1b2c3d4-1111-2222-3333-444455556666
    BeneficiaryBankAccountInput:
      type: object
      title: Beneficiary Bank Account Input
      description: Bank account to attach
      required:
        - displayName
        - accountHolderName
        - currency
        - country
        - accountType
      properties:
        displayName:
          type: string
          description: Display name for the bank account
          example: Sherlock GBP account
        accountHolderName:
          type: string
          description: Name of the account holder
          example: Sherlock Holmes
        currency:
          type: string
          description: ISO 4217 currency code
          example: GBP
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: GB
        accountType:
          type: string
          description: Bank account type
          example: CHECKING
        iban:
          type:
            - string
            - 'null'
          description: International Bank Account Number
        accountNumber:
          type:
            - string
            - 'null'
          description: Local account number
        swiftBic:
          type:
            - string
            - 'null'
          description: SWIFT / BIC code
        bankCode:
          type:
            - string
            - 'null'
          description: Local bank / routing code
        bankName:
          type:
            - string
            - 'null'
          description: Name of the bank
        bankAddress:
          oneOf:
            - $ref: '#/components/schemas/BeneficiaryAddress'
            - type: 'null'
        intermediaryBank:
          oneOf:
            - $ref: '#/components/schemas/IntermediaryBankInput'
            - type: 'null'
    IntermediaryBankInput:
      type: object
      title: Intermediary Bank Input
      description: >-
        Deprecated and ignored. RouteFusion generates the correspondent bank
        itself, so this field has no effect and will be removed.
      required:
        - bankName
        - routingCode
      properties:
        bankName:
          type: string
          description: Name of the intermediary bank
          example: JPMorgan Chase Bank, N.A.
        routingCode:
          type: string
          description: Routing code of the intermediary bank (e.g. US ABA)
          example: '021000021'
  examples:
    CreateBeneficiaryRequestBusinessWallet:
      value:
        type: BUSINESS
        name: Nimbus Settlement Ltd
        displayName: Nimbus Settlement Ltd
        email: treasury@nimbus-settlement.com
        relationshipToUser: THIRD_PARTY
        address:
          addressLine1: 25 Sir John Rogerson's Quay
          city: Dublin
          stateProvince: County Dublin
          postalCode: D02 XY45
          countryCode: IE
        instrument:
          type: BLOCKCHAIN_WALLET
          displayName: Nimbus settlement wallet
          walletAddress: '0x9f8B4a71Cc0Ed2b3F6a9E7c1D5b8A2f4E6c04C21'
          currency: USDC_ETH
          idempotencyKey: a1b2c3d4-1111-2222-3333-444455556666
    CreateBeneficiaryRequestSelfWallet:
      value:
        type: BUSINESS
        name: Harbour Freight Holdings
        displayName: Our treasury wallet
        relationshipToUser: SELF
        address:
          addressLine1: 1 Market Street
          city: San Francisco
          stateProvince: CA
          postalCode: '94105'
          countryCode: US
        instrument:
          type: BLOCKCHAIN_WALLET
          displayName: Treasury wallet
          walletAddress: '0x2d7c1f5a90b3E4c86d1A0f7b2C5e8D3a6F9b41C0'
          currency: USDC_BASE
          idempotencyKey: b2c3d4e5-2222-3333-4444-555566667777
    CreateBeneficiaryRequestPersonUsBankAccount:
      value:
        type: PERSON
        firstName: Sherlock
        lastName: Holmes
        displayName: Sherlock Holmes
        email: sherlock@baker-street.example
        relationshipToUser: THIRD_PARTY
        address:
          addressLine1: 1 Market Street
          city: San Francisco
          stateProvince: CA
          postalCode: '94105'
          countryCode: US
        instrument:
          type: BANK_ACCOUNT
          idempotencyKey: c3d4e5f6-3333-4444-5555-666677778888
          bankAccount:
            displayName: Sherlock USD checking
            accountHolderName: Sherlock Holmes
            currency: USD
            country: US
            accountType: CHECKING
            accountNumber: '1234567890'
            bankCode: '021000021'
            bankName: JPMorgan Chase Bank, N.A.
    CreateBeneficiaryRequestBusinessSwift:
      value:
        type: BUSINESS
        name: Baker Street Ltd
        displayName: Baker Street Ltd
        email: payouts@baker-street.example
        relationshipToUser: THIRD_PARTY
        address:
          addressLine1: 221B Baker Street
          city: London
          stateProvince: Greater London
          postalCode: NW1 6XE
          countryCode: GB
        instrument:
          type: BANK_ACCOUNT
          idempotencyKey: d4e5f6a7-4444-5555-6666-777788889999
          bankAccount:
            displayName: Baker Street USD
            accountHolderName: Baker Street Ltd
            currency: USD
            country: GB
            accountType: CHECKING
            iban: GB33BUKB20201555555555
            swiftBic: BARCGB22
            bankName: Barclays Bank PLC
            bankAddress:
              addressLine1: 1 Churchill Place
              city: London
              stateProvince: Greater London
              postalCode: E14 5HP
              countryCode: GB
    CreateBeneficiaryBusinessWithWallet:
      value:
        id: uspay-z2oaq71hlo7fhvck2xw0nidg
        counterpartyId: uspay-z2oaq71hlo7fhvck2xw0nidg
        createdAt: '2026-09-09T20:39:30Z'
        updatedAt: '2026-09-09T20:39:30Z'
        name: Nimbus Settlement Ltd
        displayName: Nimbus Settlement Ltd
        email: treasury@nimbus-settlement.com
        address:
          addressLine1: 25 Sir John Rogerson's Quay
          city: Dublin
          stateProvince: County Dublin
          postalCode: D02 XY45
          countryCode: IE
        relationshipToUser: THIRD_PARTY
        type: BUSINESS
    CreateBeneficiaryPersonWithBankAccount:
      value:
        id: uspay-rb5b65cstfldk53lrnaon01r
        counterpartyId: uspay-rb5b65cstfldk53lrnaon01r
        createdAt: '2026-09-09T20:39:57Z'
        updatedAt: '2026-09-09T20:39:57Z'
        firstName: Sherlock
        lastName: Holmes
        displayName: Sherlock Holmes
        email: sherlock@baker-street.example
        address:
          addressLine1: 1 Market Street
          city: San Francisco
          stateProvince: CA
          postalCode: '94105'
          countryCode: US
        relationshipToUser: THIRD_PARTY
        type: PERSON
  securitySchemes:
    meridian-account-jwt:
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer token authentication, for client-server calls.


        Send the access token issued by `POST /v1/auth/token` as `Authorization:
        Bearer {token}`. The token carries its own program and user context, so
        the `X-Meridian-*` headers are not required. See
        [Authentication](/products/meridian-accounts/guides/authentication-overview).
      type: http
    partner-api-key:
      name: X-Meridian-Signature
      in: header
      description: >-
        Meridian HMAC header authentication, for server-to-server calls.


        Required headers:
          - `X-Meridian-Api-Key`
          - `X-Meridian-Timestamp`
          - `X-Meridian-Program-Id`
          - `X-Meridian-User-Id` (MULTI_USER integrations only)
          - `X-Meridian-Signature`

        `X-Meridian-Signature` is the HMAC SHA-256 signature of the canonical
        request string, computed per request. See
        [Authentication](/products/meridian-accounts/guides/authentication-overview)
        for how to construct it.
      type: apiKey

````