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

# Preview an external bank payout for a ready customer account

> Preview a same-currency fiat payout to an external bank.

Preview a same-currency fiat payout to an external bank.

Requires `available >= amount`. Call [`payout-methods`](/customers/payouts) (and [`payout-banks`](/customers/payouts) for local rails) first. Returns `preview_token`; fees may be `pending_confirm` until confirm.

Guide: [External bank payouts](/customers/payouts).


## OpenAPI

````yaml /api-reference/openapi.json post /partner/customers/{customer_id}/accounts/{account_id}/payouts/preview
openapi: 3.1.0
info:
  title: Element Pay Partner API
  description: >-
    Provider-neutral fiat ↔ crypto ramps for partners. Discover corridors,
    create a binding quote, accept it, and receive webhooks. African local fiat
    (mobile money and bank) is auto-routed by corridor.
  version: 1.0.0
servers:
  - url: https://sandbox.elementpay.net/api/v1
    description: Sandbox
security:
  - APIKeyHeader: []
tags:
  - name: partner
    description: >-
      Corridor discovery, indicative rates, binding quotes, and order acceptance
      (including order-path account currency conversion rails). Customer ledger
      conversions use partner-customer-transfers `/conversions`.
    x-group: Partner
  - name: partner-customers
    description: >-
      Vault KYC: requirements, create, list, get/update, documents, submit, and
      revoke (`pcus_*`).
    x-group: Customers
  - name: partner-customer-accounts
    description: >-
      Customer deposit rails: open / list / get accounts and deposit
      instructions.
    x-group: Customer accounts
  - name: partner-customer-transfers
    description: >-
      On-ledger money movement: stablecoin sends, same-currency book transfers,
      and cross-currency conversions.
    x-group: Customer transfers
  - name: partner-customer-payouts
    description: >-
      External bank payouts: scheme discovery, local bank directory
      (NGN/GHS/CAD), preview, confirm, and status.
    x-group: Customer payouts
paths:
  /partner/customers/{customer_id}/accounts/{account_id}/payouts/preview:
    post:
      tags:
        - partner-customer-payouts
      summary: Preview an external bank payout for a ready customer account
      description: Preview a same-currency fiat payout to an external bank.
      operationId: >-
        partner_customer_preview_payout_partner_customers__customer_id__accounts__account_id__payouts_preview_post
      parameters:
        - name: customer_id
          in: path
          required: true
          schema:
            type: string
            description: Public customer id returned by POST /partner/customers
            examples:
              - pcus_a1b2c3d4e5f6
            title: Customer Id
          description: Public customer id returned by POST /partner/customers
          example: pcus_a1b2c3d4e5f6
        - name: account_id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
            description: Account id returned by the customer account API
            title: Account Id
          description: Account id returned by the customer account API
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerEntityPayoutPreviewRequest'
      responses:
        '201':
          description: Preview token for confirm. Fee often pending_confirm until confirm.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerSuccessEnvelope'
              example:
                status: success
                message: Payout preview
                data:
                  preview_token: nvpay.eyJhbGciOiJIUzI1NiJ9.preview
                  currency: NGN
                  from_account_id: 39
                  amount: '1.00'
                  fee: null
                  receive_amount: null
                  fee_status: pending_confirm
                  scheme: nip
                  destination:
                    rail: bank
                    country: NG
                    scheme: nip
                    bank_name: Access Bank
                    account_number_masked: '****0031'
                  expires_at: '2026-09-14T12:10:00+00:00'
                  customer_id: pcus_a1b2c3d4e5f6
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - message
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  message:
                    type: string
                  data:
                    type:
                      - object
                      - 'null'
              example:
                status: error
                message: Unauthorized
                data: null
        '422':
          description: Insufficient balance or invalid bank fields
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - message
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  message:
                    type: string
                  data:
                    type:
                      - object
                      - 'null'
              example:
                status: error
                message: Insufficient balance
                data:
                  available: '0.00'
                  amount: '1.00'
                  currency: NGN
      security:
        - APIKeyHeader: []
components:
  schemas:
    PartnerEntityPayoutPreviewRequest:
      properties:
        amount:
          type: string
          title: Amount
          description: Decimal amount in account currency, e.g. 1.00
        beneficiary:
          $ref: '#/components/schemas/PartnerEntityPayoutBeneficiary'
        bank:
          $ref: '#/components/schemas/PartnerEntityPayoutBank'
        security_question:
          anyOf:
            - type: string
              maxLength: 256
              minLength: 1
            - type: 'null'
          title: Security Question
          description: >-
            CAD Interac outbound only: question the recipient must answer to
            deposit. Requires security_answer. Mapped upstream as
            payment-details meta.
        security_answer:
          anyOf:
            - type: string
              maxLength: 128
              minLength: 1
            - type: 'null'
          title: Security Answer
          description: >-
            CAD Interac outbound only: answer for security_question. Share with
            the recipient out-of-band; never returned in partner responses.
      type: object
      required:
        - amount
        - beneficiary
        - bank
      title: PartnerEntityPayoutPreviewRequest
      description: >-
        Preview an external bank payout from a fiat account (same-currency, no
        FX).
    PartnerSuccessEnvelope:
      type: object
      required:
        - status
        - message
        - data
      properties:
        status:
          type: string
          enum:
            - success
        message:
          type: string
        data:
          type: object
    PartnerEntityPayoutBeneficiary:
      properties:
        first_name:
          type: string
          maxLength: 64
          minLength: 1
          title: First Name
        last_name:
          type: string
          maxLength: 64
          minLength: 1
          title: Last Name
        email:
          type: string
          maxLength: 254
          minLength: 3
          title: Email
        address:
          $ref: '#/components/schemas/PartnerEntityResidentialAddress'
      type: object
      required:
        - first_name
        - last_name
        - email
        - address
      title: PartnerEntityPayoutBeneficiary
      description: External payout recipient identity (counterparty).
    PartnerEntityPayoutBank:
      properties:
        scheme:
          anyOf:
            - type: string
            - type: 'null'
          title: Scheme
          description: >-
            CAD: eft|interac_email|interac_account; USD: ach|wire; NGN: nip;
            GHS: gh_eft|eft; swift for cross-border / non-local corridors
        swift_bic:
          anyOf:
            - type: string
            - type: 'null'
          title: Swift Bic
          description: Required for scheme=swift
        iban:
          anyOf:
            - type: string
            - type: 'null'
          title: Iban
        routing_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Routing Number
        account_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Account Type
          description: USD — checking or savings
        bank_institution_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Bank Institution Number
          description: CAD EFT / Interac account — 3 digits
        transit_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Transit Number
          description: CAD EFT / Interac account — 5 digits
        bank_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Bank Code
          description: Local bank code — NGN NIP, GHS EFT (and similar bank-code rails)
        account_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Account Number
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
          description: >-
            Required for CAD scheme=interac_email (Interac e-Transfer
            destination)
        account_holder_name:
          type: string
          maxLength: 128
          minLength: 1
          title: Account Holder Name
        bank_name:
          anyOf:
            - type: string
              maxLength: 128
              minLength: 1
            - type: 'null'
          title: Bank Name
          description: Required except CAD interac_email
        country:
          type: string
          maxLength: 2
          minLength: 2
          title: Country
          description: ISO-3166 alpha-2
      type: object
      required:
        - account_holder_name
        - country
      title: PartnerEntityPayoutBank
      description: >-
        External bank destination. Required fields depend on account currency /
        scheme. CAD local: scheme ``eft`` (default) | ``interac_email`` |
        ``interac_account`` - eft / interac_account: bank_institution_number
        (3), transit_number (5), account_number, bank_name, country=CA -
        interac_email: email, account_holder_name, country=CA (bank_name
        optional) EUR SEPA: iban, country (EU), optional swift_bic USD ACH/wire:
        routing_number, account_number, country=US, optional scheme/account_type
        NGN NIP: bank_code, account_number, bank_name, country=NG (scheme
        ``nip`` or omit) GHS EFT: bank_code, account_number, bank_name,
        country=GH (scheme ``gh_eft``, ``eft``, or omit) SWIFT: scheme=swift,
        swift_bic, plus iban or account_number (any supported currency)
    PartnerEntityResidentialAddress:
      properties:
        line_1:
          type: string
          title: Line 1
        city:
          type: string
          title: City
        country:
          type: string
          maxLength: 2
          minLength: 2
          title: Country
          description: ISO-3166 alpha-2
        line_2:
          anyOf:
            - type: string
            - type: 'null'
          title: Line 2
        state:
          anyOf:
            - type: string
            - type: 'null'
          title: State
        postal_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Postal Code
      type: object
      required:
        - line_1
        - city
        - country
      title: PartnerEntityResidentialAddress
      description: Partner address shape; mapped to upstream ``country_code`` on attach.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````