> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rails.wayex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Check a payee name

> Checks the name you hold for an AUD bank account against the name the receiving bank has registered (`type: bank_account`), or resolves a PayID to the name it is registered to (`type: payid`).

## What this endpoint does

Checks the name you hold for an AUD bank account against the name the receiving bank has registered (`type: bank_account`), or resolves a PayID to the name it is registered to (`type: payid`).

## When to use it

Call it before you save an AUD payout destination, or use the `payeeCheck` field on off-ramp route and Treasury beneficiary creation to run the check in the same request. Pass the returned `id` as `payeeCheck.checkId` there to reuse this check instead of paying for a second one.

## Before you call

Use a secret API key with `payees:write`. Confirmation of Payee must be enabled for your account by Wayex; otherwise the request is refused with `403 confirmation_of_payee_not_enabled`. A name with fewer than two printable characters, or details that fail validation, are refused with `400` before anything is checked.

## Money and balance effect

This moves no money. Each answered check — any `result`, including `no_match` and `not_found` — is billed per your fee schedule on your monthly invoice (default AUD 0.40 per check, plus GST if your account is charged GST); `fee.amount` is what this check was charged. Refused and failed checks (`400`, `403`, `422 payee_details_invalid`, `429 payee_check_limit_reached`, `502`, `503 payee_check_unavailable`) are not billed.

## States and completion

The check is complete when it is returned; there is no later update or webhook. A non-match is still an answer: branch on `result` and `confirmed` (true for `match` and `close_match`), and show `message` as returned. For a PayID, `displayName` is the name it is registered to; the linked bank account is never returned.

## Safe retries

Send a unique `Idempotency-Key` per check. If the response is lost, or you receive `502`, retry the same payload with the same key: a retry returns the original check and never bills twice. A new key runs, and bills, a new check.

Read [Confirm payee](https://docs.rails.wayex.com/console/overview.md#confirm-payee) for the complete workflow.


## OpenAPI

````yaml /api-reference/openapi.json post /v1/payee-checks
openapi: 3.0.0
info:
  title: Wayex API
  description: >-
    Wayex APIs for direct customer payment routes and isolated, prefunded
    Treasury accounts. Each API key is bound to one tenant account and its own
    wallet, settings, webhooks, and reporting.
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.sandbox.rails.wayex.com
    description: Sandbox — fully simulated providers, no real funds move
  - url: https://api.rails.wayex.com
    description: Production — live rails, real funds move
security:
  - Bearer: []
  - ApiKey: []
tags:
  - name: Treasury
    description: >-
      Prefunded AUD and stablecoin wallets for one isolated tenant account.
      Fund, pay, convert, withdraw, track, and reconcile without selecting
      another account.
  - name: Customers
    description: >-
      Onboard end customers, run verification, and manage each customer's
      entitlements.
  - name: Payment routes
    description: >-
      Standing deposit instructions per customer. When a customer funds a route,
      Wayex auto-converts at the live rate and pays out/sends — no quote, no
      lock.
  - name: Transfers
    description: >-
      Read the conversion records produced when customers fund payment routes —
      the live activity feed and per-conversion lifecycle timeline — and, on
      client-gated routes, progress or refund a waiting payment.
  - name: Rates
    description: >-
      The live indicative AUD↔stablecoin rate right now — the all-in rate Wayex
      quotes. Indicative only; the binding price is struck when a route's funds
      land, or when you progress a client-gated payment.
  - name: Revenue
    description: Your developer-fee revenue over time.
  - name: Invoices
    description: >-
      Your monthly invoices — Wayex platform fees due, net of your accrued
      developer-fee credit.
  - name: Webhooks
    description: Subscribe to HMAC-signed event webhooks and inspect deliveries.
  - name: API keys
    description: Create, list, and rotate API keys for programmatic access.
  - name: Fees
    description: >-
      Configure your developer fee — the markup withheld from each conversion
      and credited against your monthly invoice.
  - name: Invitations
    description: Accept a team invitation and activate your account.
  - name: Team
    description: Manage your own team — list members and send console invitations.
  - name: Notification settings
    description: >-
      Manage whether Wayex sends customer-facing notification emails on your
      behalf.
paths:
  /v1/payee-checks:
    post:
      tags: []
      summary: Check a payee name
      description: >-
        Checks the name you hold for an AUD bank account against the name the
        receiving bank has registered (`type: bank_account`), or resolves a
        PayID to the name it is registered to (`type: payid`). Call it before
        you save an AUD payout destination, or use the `payeeCheck` field on
        off-ramp route and Treasury beneficiary creation to run the check in the
        same request. Pass the returned `id` as `payeeCheck.checkId` there to
        reuse this check instead of paying for a second one.
      operationId: PayeeCheckController2_create_v1
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: >-
            A unique key for this logical action. Reuse the same key and
            identical payload when retrying after an unknown response.
          schema:
            type: string
            minLength: 8
            maxLength: 255
          example: 13bda8d7-87bd-4fa4-b7d5-e740725f9bd2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  properties:
                    type:
                      description: Check the name on an AUD bank account.
                      type: string
                      enum:
                        - bank_account
                    bsb:
                      description: >-
                        The 6-digit BSB of the account to check (`NNNNNN` or
                        `NNN-NNN`).
                      type: string
                      pattern: ^\d{3}-?\d{3}$
                    accountNumber:
                      description: The account number to check (1-9 digits).
                      type: string
                      pattern: ^\d{1,9}$
                    accountName:
                      description: >-
                        The account holder name to check against the registered
                        name (2-140 characters).
                      type: string
                      minLength: 2
                      maxLength: 140
                  required:
                    - type
                    - bsb
                    - accountNumber
                    - accountName
                - type: object
                  properties:
                    type:
                      description: Resolve a PayID to its registered name.
                      type: string
                      enum:
                        - payid
                    payId:
                      description: The PayID to resolve (email, phone or ABN).
                      type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - email
                            - phone
                            - abn
                        value:
                          type: string
                          minLength: 1
                      required:
                        - type
                        - value
                  required:
                    - type
                    - payId
      responses:
        '201':
          description: The check result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    description: The payee check id (`pchk_` + 32 hex characters).
                    type: string
                    pattern: ^pchk_[0-9a-f]{32}$
                  type:
                    description: >-
                      What is checked: an AUD bank account (BSB + account number
                      + name) or a PayID.
                    type: string
                    enum:
                      - bank_account
                      - payid
                  bankAccount:
                    description: >-
                      The bank account checked. Present when `type` is
                      `bank_account`.
                    type: object
                    properties:
                      bsb:
                        description: The 6-digit BSB checked.
                        type: string
                        pattern: ^\d{6}$
                      accountNumber:
                        description: The account number checked.
                        type: string
                        minLength: 1
                      accountName:
                        description: The account holder name checked.
                        type: string
                        minLength: 1
                    required:
                      - bsb
                      - accountNumber
                      - accountName
                  payId:
                    description: The PayID resolved. Present when `type` is `payid`.
                    type: object
                    properties:
                      type:
                        description: The PayID type.
                        type: string
                        enum:
                          - email
                          - phone
                          - abn
                      value:
                        description: The PayID resolved.
                        type: string
                        minLength: 1
                    required:
                      - type
                      - value
                  result:
                    description: >-
                      The outcome of the check: `match` (the name matches),
                      `close_match` (the name is close to the registered name),
                      `no_match` (the name does not match), `not_found` (no such
                      account or PayID) or `closed` (the account is closed). A
                      resolved PayID is `match`.
                    type: string
                    enum:
                      - match
                      - close_match
                      - no_match
                      - not_found
                      - closed
                  indicator:
                    description: >-
                      The icon to show with the result: `tick` (confirmed),
                      `warning` (close match), `cross` (not confirmed) or `dash`
                      (no answer about the name).
                    type: string
                    enum:
                      - tick
                      - warning
                      - cross
                      - dash
                  message:
                    description: >-
                      The result message to show the user, as supplied. Show it
                      as is.
                    type: string
                    minLength: 1
                  displayName:
                    description: >-
                      The registered name, when the receiving institution
                      permits it to be shown (for a PayID, the name it is
                      registered to).
                    type: string
                    minLength: 1
                  confirmed:
                    description: >-
                      True when `result` is `match` or `close_match`. An
                      unconfirmed check needs `acceptMismatch: true` to be used
                      on a payment route or beneficiary.
                    type: boolean
                  fee:
                    description: >-
                      The fee charged for this check, billed on your monthly
                      invoice.
                    type: object
                    properties:
                      amount:
                        description: >-
                          The fee charged for this check, as a decimal string
                          ("0.00" when no fee applies).
                        type: string
                        pattern: ^\d+(\.\d+)?$
                      currency:
                        type: string
                        enum:
                          - AUD
                    required:
                      - amount
                      - currency
                  createdAt:
                    description: When the check was run.
                    type: string
                    format: date-time
                required:
                  - id
                  - type
                  - result
                  - message
                  - confirmed
                  - fee
                  - createdAt
        '400':
          description: Validation failed.
        '403':
          description: Confirmation of Payee is not enabled for this account.
        '422':
          description: >-
            The details were not accepted for checking
            (`payee_details_invalid`).
        '429':
          description: >-
            The payee check limit has been reached
            (`payee_check_limit_reached`).
        '502':
          description: >-
            The check could not be completed; retry with the same
            Idempotency-Key.
        '503':
          description: >-
            Payee checks are temporarily unavailable
            (`payee_check_unavailable`).
      security:
        - Bearer: []
        - ApiKey: []
components:
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: Wayex API key
      description: 'Send the same Wayex API key as `Authorization: Bearer <key>`.'
    ApiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >-
        A Wayex API key. Use a secret key (`sk_…`) — it works on every endpoint.
        Publishable keys (`pk_…`) are accepted only on a small set of read
        endpoints: `GET /v1/rates`, `GET /v1/activity`, `GET
        /v1/developer-fees`, `GET /v1/revenue`, and `GET /v1/reports/revenue`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.