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

# Read payout capabilities for one recipient

> What a payout to this recipient would be allowed to do: one option per bank rail of the user's that could reach them, each carrying its limits, fees, memo and purpose-code rules, and the blockers that stand in the way. Reads the provider's live channel catalogue where one exists (Due), falling back to our declarations otherwise. Takes either a saved `contactId` or raw `account` requisites; books, quotes and writes nothing.



## OpenAPI

````yaml /openapi.json post /api/v1/balance/payout/recipient/capabilities
openapi: 3.1.0
info:
  title: HEVN API
  description: Backend API for HEVN mobile neobank
  version: 0.1.2
servers: []
security: []
paths:
  /api/v1/balance/payout/recipient/capabilities:
    post:
      tags:
        - Balance
      summary: Read payout capabilities for one recipient
      description: >-
        What a payout to this recipient would be allowed to do: one option per
        bank rail of the user's that could reach them, each carrying its limits,
        fees, memo and purpose-code rules, and the blockers that stand in the
        way. Reads the provider's live channel catalogue where one exists (Due),
        falling back to our declarations otherwise. Takes either a saved
        `contactId` or raw `account` requisites; books, quotes and writes
        nothing.
      operationId: >-
        read_recipient_payout_capabilities_api_v1_balance_payout_recipient_capabilities_post
      parameters:
        - name: x-api-key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecipientCapabilitiesRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipientPayoutCapabilities'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    RecipientCapabilitiesRequest:
      properties:
        contactId:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Contactid
        account:
          anyOf:
            - oneOf:
                - $ref: '#/components/schemas/SepaAccountInput'
                - $ref: '#/components/schemas/SwiftAccountInput'
                - $ref: '#/components/schemas/AchAccountInput'
                - $ref: '#/components/schemas/UaeAccountInput'
                - $ref: '#/components/schemas/UkFpsAccountInput'
                - $ref: '#/components/schemas/PixAccountInput'
            - type: 'null'
          title: Account
          description: Recipient requisites
        address:
          anyOf:
            - $ref: '#/components/schemas/UserAddress'
            - type: 'null'
        relationship:
          anyOf:
            - $ref: '#/components/schemas/ContactRelationship'
            - type: 'null'
        amount:
          anyOf:
            - type: number
              exclusiveMinimum: 0
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Amount
      type: object
      title: RecipientCapabilitiesRequest
      description: >-
        Ask what a payout to one recipient would be allowed to do.


        Either end of the client's flow answers the same question, so the
        request

        takes either: ``contactId`` for a recipient already saved, ``account``
        for

        the form that has not been submitted yet. ``amount`` is optional and
        only

        has the rail limits checked against it — nothing is quoted or booked.
    RecipientPayoutCapabilities:
      properties:
        recipient:
          $ref: '#/components/schemas/RecipientSummary'
        available:
          type: boolean
          title: Available
        options:
          items:
            $ref: '#/components/schemas/RecipientPayoutOption'
          type: array
          title: Options
        blockers:
          items:
            $ref: '#/components/schemas/RecipientBlocker'
          type: array
          title: Blockers
      type: object
      required:
        - recipient
        - available
      title: RecipientPayoutCapabilities
      description: Everything one recipient can be paid with, and what stands in the way.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SepaAccountInput:
      properties:
        accountHolderType:
          $ref: '#/components/schemas/AlignAccountHolderType'
        accountHolderFirstName:
          anyOf:
            - type: string
            - type: 'null'
          title: Accountholderfirstname
        accountHolderLastName:
          anyOf:
            - type: string
            - type: 'null'
          title: Accountholderlastname
        accountHolderBusinessName:
          anyOf:
            - type: string
            - type: 'null'
          title: Accountholderbusinessname
        businessIndustry:
          anyOf:
            - type: string
              pattern: ^\d{6}$
            - type: 'null'
          title: Businessindustry
          description: >-
            6-digit NAICS 2022 industry code for business recipients. Required
            by Swipelux before US ACH payout destinations of business recipients
            can be activated; ignored for individual recipients.
        accountType:
          type: string
          const: sepa
          title: Accounttype
          default: sepa
        iban:
          type: string
          title: Iban
        bic:
          anyOf:
            - type: string
            - type: 'null'
          title: Bic
        currency:
          type: string
          title: Currency
          default: EUR
        bankName:
          type: string
          title: Bankname
        relationship:
          anyOf:
            - $ref: '#/components/schemas/ContactRelationship'
            - type: 'null'
      type: object
      required:
        - accountHolderType
        - iban
        - bankName
      title: SepaAccountInput
      description: SEPA bank contact input.
    SwiftAccountInput:
      properties:
        accountHolderType:
          $ref: '#/components/schemas/AlignAccountHolderType'
        accountHolderFirstName:
          anyOf:
            - type: string
            - type: 'null'
          title: Accountholderfirstname
        accountHolderLastName:
          anyOf:
            - type: string
            - type: 'null'
          title: Accountholderlastname
        accountHolderBusinessName:
          anyOf:
            - type: string
            - type: 'null'
          title: Accountholderbusinessname
        businessIndustry:
          anyOf:
            - type: string
              pattern: ^\d{6}$
            - type: 'null'
          title: Businessindustry
          description: >-
            6-digit NAICS 2022 industry code for business recipients. Required
            by Swipelux before US ACH payout destinations of business recipients
            can be activated; ignored for individual recipients.
        accountType:
          type: string
          const: swift
          title: Accounttype
          default: swift
        bic:
          type: string
          title: Bic
        bankName:
          type: string
          title: Bankname
        accountNumber:
          type: string
          title: Accountnumber
        currency:
          type: string
          title: Currency
          default: USD
        bankAddress:
          anyOf:
            - $ref: '#/components/schemas/BankAddressInput'
            - type: 'null'
        routingNumber:
          anyOf:
            - type: string
            - type: 'null'
          title: Routingnumber
        relationship:
          anyOf:
            - $ref: '#/components/schemas/ContactRelationship'
            - type: 'null'
      type: object
      required:
        - accountHolderType
        - bic
        - bankName
        - accountNumber
      title: SwiftAccountInput
      description: SWIFT bank contact input.
    AchAccountInput:
      properties:
        accountHolderType:
          $ref: '#/components/schemas/AlignAccountHolderType'
        accountHolderFirstName:
          anyOf:
            - type: string
            - type: 'null'
          title: Accountholderfirstname
        accountHolderLastName:
          anyOf:
            - type: string
            - type: 'null'
          title: Accountholderlastname
        accountHolderBusinessName:
          anyOf:
            - type: string
            - type: 'null'
          title: Accountholderbusinessname
        businessIndustry:
          anyOf:
            - type: string
              pattern: ^\d{6}$
            - type: 'null'
          title: Businessindustry
          description: >-
            6-digit NAICS 2022 industry code for business recipients. Required
            by Swipelux before US ACH payout destinations of business recipients
            can be activated; ignored for individual recipients.
        accountType:
          type: string
          enum:
            - ach
            - fedwire
          title: Accounttype
          default: ach
        bankName:
          type: string
          title: Bankname
          default: ''
        accountNumber:
          type: string
          title: Accountnumber
        routingNumber:
          type: string
          title: Routingnumber
        currency:
          type: string
          title: Currency
          default: USD
        bankAddress:
          anyOf:
            - $ref: '#/components/schemas/BankAddressInput'
            - type: 'null'
        relationship:
          anyOf:
            - $ref: '#/components/schemas/ContactRelationship'
            - type: 'null'
      type: object
      required:
        - accountHolderType
        - accountNumber
        - routingNumber
      title: AchAccountInput
      description: ACH bank contact input.
    UaeAccountInput:
      properties:
        accountHolderType:
          $ref: '#/components/schemas/AlignAccountHolderType'
        accountHolderFirstName:
          anyOf:
            - type: string
            - type: 'null'
          title: Accountholderfirstname
        accountHolderLastName:
          anyOf:
            - type: string
            - type: 'null'
          title: Accountholderlastname
        accountHolderBusinessName:
          anyOf:
            - type: string
            - type: 'null'
          title: Accountholderbusinessname
        businessIndustry:
          anyOf:
            - type: string
              pattern: ^\d{6}$
            - type: 'null'
          title: Businessindustry
          description: >-
            6-digit NAICS 2022 industry code for business recipients. Required
            by Swipelux before US ACH payout destinations of business recipients
            can be activated; ignored for individual recipients.
        accountType:
          type: string
          const: uaefts
          title: Accounttype
          default: uaefts
        bankName:
          type: string
          title: Bankname
        currency:
          type: string
          title: Currency
          default: AED
        ibanNumber:
          type: string
          title: Ibannumber
        bic:
          anyOf:
            - type: string
            - type: 'null'
          title: Bic
        relationship:
          anyOf:
            - $ref: '#/components/schemas/ContactRelationship'
            - type: 'null'
      type: object
      required:
        - accountHolderType
        - bankName
        - ibanNumber
      title: UaeAccountInput
      description: UAE FTS bank contact input.
    UkFpsAccountInput:
      properties:
        accountHolderType:
          $ref: '#/components/schemas/AlignAccountHolderType'
        accountHolderFirstName:
          anyOf:
            - type: string
            - type: 'null'
          title: Accountholderfirstname
        accountHolderLastName:
          anyOf:
            - type: string
            - type: 'null'
          title: Accountholderlastname
        accountHolderBusinessName:
          anyOf:
            - type: string
            - type: 'null'
          title: Accountholderbusinessname
        businessIndustry:
          anyOf:
            - type: string
              pattern: ^\d{6}$
            - type: 'null'
          title: Businessindustry
          description: >-
            6-digit NAICS 2022 industry code for business recipients. Required
            by Swipelux before US ACH payout destinations of business recipients
            can be activated; ignored for individual recipients.
        accountType:
          type: string
          const: ukfps
          title: Accounttype
          default: ukfps
        bankName:
          type: string
          title: Bankname
        accountNumber:
          type: string
          title: Accountnumber
        sortCode:
          anyOf:
            - type: string
            - type: 'null'
          title: Sortcode
        routingNumber:
          anyOf:
            - type: string
            - type: 'null'
          title: Routingnumber
        currency:
          type: string
          title: Currency
          default: GBP
        relationship:
          anyOf:
            - $ref: '#/components/schemas/ContactRelationship'
            - type: 'null'
      type: object
      required:
        - accountHolderType
        - bankName
        - accountNumber
      title: UkFpsAccountInput
      description: UK Faster Payments bank contact input.
    PixAccountInput:
      properties:
        accountType:
          type: string
          const: pix
          title: Accounttype
          default: pix
        pixKey:
          type: string
          title: Pixkey
        accountHolderName:
          type: string
          title: Accountholdername
        bankName:
          type: string
          title: Bankname
        currency:
          type: string
          title: Currency
          default: BRL
        relationship:
          anyOf:
            - $ref: '#/components/schemas/ContactRelationship'
            - type: 'null'
        businessIndustry:
          anyOf:
            - type: string
              pattern: ^\d{6}$
            - type: 'null'
          title: Businessindustry
          description: >-
            6-digit NAICS 2022 industry code for business recipients. Required
            by Swipelux before US ACH payout destinations of business recipients
            can be activated; ignored for individual recipients.
      type: object
      required:
        - pixKey
        - accountHolderName
        - bankName
      title: PixAccountInput
      description: >-
        Brazil PIX bank contact input.


        PIX carries a single holder name; it maps to a business holder because
        the internal

        details shape requires first+last names for individuals (mirrors the
        legacy `iban` path).
    UserAddress:
      properties:
        streetAddress:
          anyOf:
            - type: string
            - type: 'null'
          title: Streetaddress
        addressLine2:
          anyOf:
            - type: string
            - type: 'null'
          title: Addressline2
        city:
          anyOf:
            - type: string
            - type: 'null'
          title: City
        state:
          anyOf:
            - type: string
            - type: 'null'
          title: State
        country:
          anyOf:
            - $ref: '#/components/schemas/CountryCode'
            - type: 'null'
        zip:
          anyOf:
            - type: string
            - type: 'null'
          title: Zip
      type: object
      title: UserAddress
      description: >-
        Address schema for user.


        Canonical field names: street_address, address_line_2, city, state,
        country, zip.

        Accepts legacy Align/IBAN field names (street_line_1, street_line_2,
        postal_code)

        for backward compatibility with existing JSONB data.
    ContactRelationship:
      type: string
      enum:
        - employee
        - contractor
        - vendor
        - subsidiary
        - merchant
        - customer
        - landlord
        - family
        - other
        - self
      title: ContactRelationship
      description: >-
        How a payout contact relates to the user.


        The vocabulary mirrors Swipelux's recipient relationships so the common

        values project onto their API unchanged, but this is our own domain
        type:

        ``SELF`` marks a first-party payout to the user's own account at another

        bank and has no Swipelux counterpart. Providers own that projection —
        see

        ``SwipeluxRecipients._recipient_relationship`` — so nothing here depends
        on

        a provider, and no provider enum has to carry a value it cannot accept.
    RecipientSummary:
      properties:
        contactId:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Contactid
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        method:
          anyOf:
            - type: string
            - type: 'null'
          title: Method
        currency:
          anyOf:
            - type: string
            - type: 'null'
          title: Currency
        country:
          anyOf:
            - type: string
            - type: 'null'
          title: Country
        bankCountry:
          anyOf:
            - type: string
            - type: 'null'
          title: Bankcountry
        maskedAccount:
          anyOf:
            - type: string
            - type: 'null'
          title: Maskedaccount
        holderType:
          anyOf:
            - type: string
            - type: 'null'
          title: Holdertype
        relationship:
          anyOf:
            - $ref: '#/components/schemas/ContactRelationship'
            - type: 'null'
        firstParty:
          type: boolean
          title: Firstparty
          default: false
      type: object
      title: RecipientSummary
      description: Who is being paid, as the capabilities were resolved against them.
    RecipientPayoutOption:
      properties:
        provider:
          $ref: '#/components/schemas/FiatProvider'
        bankAccountId:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Bankaccountid
        bankRail:
          type: string
          title: Bankrail
        providerRail:
          anyOf:
            - type: string
            - type: 'null'
          title: Providerrail
        method:
          type: string
          title: Method
        methodName:
          type: string
          title: Methodname
        currency:
          type: string
          title: Currency
        available:
          type: boolean
          title: Available
        minAmount:
          type: number
          title: Minamount
        maxAmount:
          anyOf:
            - type: number
            - type: 'null'
          title: Maxamount
        fixedFee:
          anyOf:
            - type: number
            - type: 'null'
          title: Fixedfee
        feeBps:
          type: number
          title: Feebps
          default: 0
        estimatedRecipientAmount:
          anyOf:
            - type: number
            - type: 'null'
          title: Estimatedrecipientamount
        amountToSupported:
          type: boolean
          title: Amounttosupported
          default: false
        sourceTokens:
          items:
            $ref: '#/components/schemas/PayoutSourceToken'
          type: array
          title: Sourcetokens
        memo:
          $ref: '#/components/schemas/RecipientMemoRules'
        purpose:
          $ref: '#/components/schemas/RecipientPurposeRules'
        documents:
          $ref: '#/components/schemas/RecipientDocumentRules'
        blockers:
          items:
            $ref: '#/components/schemas/RecipientBlocker'
          type: array
          title: Blockers
        live:
          type: boolean
          title: Live
          default: false
      type: object
      required:
        - provider
        - bankRail
        - method
        - methodName
        - currency
        - available
        - minAmount
      title: RecipientPayoutOption
      description: >-
        One way this recipient can be paid: a bank rail of ours, a method, a

        provider and everything that rail then demands.


        ``available`` is the whole answer to "can I send to this bank": false
        with

        an empty ``blockers`` list never happens — something always says why.
    RecipientBlocker:
      properties:
        code:
          $ref: '#/components/schemas/RecipientBlockerCode'
        message:
          type: string
          title: Message
        fields:
          items:
            type: string
          type: array
          title: Fields
      type: object
      required:
        - code
        - message
      title: RecipientBlocker
      description: One reason a payout is refused, and what would clear it.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    AlignAccountHolderType:
      type: string
      enum:
        - individual
        - business
      title: AlignAccountHolderType
      description: Account holder type.
    BankAddressInput:
      properties:
        addressLine1:
          type: string
          maxLength: 120
          minLength: 1
          title: Addressline1
        city:
          type: string
          maxLength: 80
          minLength: 1
          title: City
        state:
          anyOf:
            - type: string
              maxLength: 80
            - type: 'null'
          title: State
        postalCode:
          anyOf:
            - type: string
              maxLength: 32
            - type: 'null'
          title: Postalcode
        country:
          type: string
          maxLength: 3
          minLength: 2
          title: Country
      type: object
      required:
        - addressLine1
        - city
        - country
      title: BankAddressInput
      description: >-
        What a client must provide for a bank address: everything the banking
        provider requires.


        the banking provider caps the street at 120 and the city at 80; the
        country is what the

        payout carries in ``bankAddress.country`` (both ISO alpha-2 and alpha-3
        are

        accepted there), though a payout prefers the BIC-derived one.
    CountryCode:
      type: string
      enum:
        - AF
        - AX
        - AL
        - DZ
        - AS
        - AD
        - AO
        - AI
        - AQ
        - AG
        - AR
        - AM
        - AW
        - AU
        - AT
        - AZ
        - BS
        - BH
        - BD
        - BB
        - BY
        - BE
        - BZ
        - BJ
        - BM
        - BT
        - BO
        - BQ
        - BA
        - BW
        - BV
        - BR
        - IO
        - BN
        - BG
        - BF
        - BI
        - CV
        - KH
        - CM
        - CA
        - KY
        - CF
        - TD
        - CL
        - CN
        - CX
        - CC
        - CO
        - KM
        - CG
        - CD
        - CK
        - CR
        - CI
        - HR
        - CU
        - CW
        - CY
        - CZ
        - DK
        - DJ
        - DM
        - DO
        - EC
        - EG
        - SV
        - GQ
        - ER
        - EE
        - SZ
        - ET
        - FK
        - FO
        - FJ
        - FI
        - FR
        - GF
        - PF
        - TF
        - GA
        - GM
        - GE
        - DE
        - GH
        - GI
        - GR
        - GL
        - GD
        - GP
        - GU
        - GT
        - GG
        - GN
        - GW
        - GY
        - HT
        - HM
        - VA
        - HN
        - HK
        - HU
        - IS
        - IN
        - ID
        - IR
        - IQ
        - IE
        - IM
        - IL
        - IT
        - JM
        - JP
        - JE
        - JO
        - KZ
        - KE
        - KI
        - KP
        - KR
        - KW
        - KG
        - LA
        - LV
        - LB
        - LS
        - LR
        - LY
        - LI
        - LT
        - LU
        - MO
        - MG
        - MW
        - MY
        - MV
        - ML
        - MT
        - MH
        - MQ
        - MR
        - MU
        - YT
        - MX
        - FM
        - MD
        - MC
        - MN
        - ME
        - MS
        - MA
        - MZ
        - MM
        - NA
        - NR
        - NP
        - NL
        - NC
        - NZ
        - NI
        - NE
        - NG
        - NU
        - NF
        - MK
        - MP
        - 'NO'
        - OM
        - PK
        - PW
        - PS
        - PA
        - PG
        - PY
        - PE
        - PH
        - PN
        - PL
        - PT
        - PR
        - QA
        - RE
        - RO
        - RU
        - RW
        - BL
        - SH
        - KN
        - LC
        - MF
        - PM
        - VC
        - WS
        - SM
        - ST
        - SA
        - SN
        - RS
        - SC
        - SL
        - SG
        - SX
        - SK
        - SI
        - SB
        - SO
        - ZA
        - GS
        - SS
        - ES
        - LK
        - SD
        - SR
        - SJ
        - SE
        - CH
        - SY
        - TW
        - TJ
        - TZ
        - TH
        - TL
        - TG
        - TK
        - TO
        - TT
        - TN
        - TR
        - TM
        - TC
        - TV
        - UG
        - UA
        - AE
        - GB
        - US
        - UM
        - UY
        - UZ
        - VU
        - VE
        - VN
        - VG
        - VI
        - WF
        - EH
        - YE
        - ZM
        - ZW
      title: CountryCode
      description: ISO 3166-1 alpha-2 country codes.
    FiatProvider:
      type: string
      enum:
        - swipelux
        - align
        - dakota
        - mcp
        - wirex
        - conduit_fiat
        - conduit_crypto
        - due
      title: FiatProvider
      description: Supported fiat payment providers.
    PayoutSourceToken:
      type: string
      enum:
        - USDC
        - EURC
      title: PayoutSourceToken
      description: |-
        Stablecoin a payout (offramp) quote is funded with.

        USDC is the default across all providers. EURC is Align-only: Align
        accepts an EURC deposit for EUR/SEPA offramps (and prices other
        destination currencies through its own FX).
    RecipientMemoRules:
      properties:
        supported:
          type: boolean
          title: Supported
          default: false
        required:
          type: boolean
          title: Required
          default: false
        minLength:
          anyOf:
            - type: integer
            - type: 'null'
          title: Minlength
        maxLength:
          anyOf:
            - type: integer
            - type: 'null'
          title: Maxlength
        requiredContent:
          items:
            type: string
          type: array
          title: Requiredcontent
      type: object
      title: RecipientMemoRules
      description: What the rail accepts as a payment reference.
    RecipientPurposeRules:
      properties:
        supported:
          type: boolean
          title: Supported
          default: false
        required:
          type: boolean
          title: Required
          default: false
        defaultCode:
          anyOf:
            - type: string
            - type: 'null'
          title: Defaultcode
        codes:
          items:
            type: string
          type: array
          title: Codes
      type: object
      title: RecipientPurposeRules
      description: The purpose-of-payment vocabulary this rail asks for, if any.
    RecipientDocumentRules:
      properties:
        supported:
          type: boolean
          title: Supported
          default: false
        required:
          type: boolean
          title: Required
          default: false
      type: object
      title: RecipientDocumentRules
      description: Supporting documents the provider wants attached to the payout.
    RecipientBlockerCode:
      type: string
      enum:
        - recipient_details_missing
        - recipient_address_incomplete
        - recipient_country_restricted
        - recipient_holder_type_unsupported
        - account_type_unsupported
        - routing_unresolved
        - no_active_bank
        - no_rail_for_method
        - currency_mismatch
        - payout_feature_disabled
        - payout_feature_on_request
        - provider_not_configured
        - sender_residency_ineligible
        - sender_category_restricted
        - endorsement_required
        - channel_unavailable
        - amount_below_minimum
        - amount_above_maximum
      title: RecipientBlockerCode
      description: >-
        Why a payout cannot be made, in codes a client can branch on.


        The message beside it is for a human; nothing should be parsed out of
        it.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````