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

# Verify Account

> Verify a Fyatu recipient account before sending a payout. Validate account existence and details. POST /payouts/verify-account.

## Overview

Verify a Fyatu account before making a payout. This confirms the account exists, is active, and can receive funds.

<Warning>
  Always verify the recipient account before making a payout to prevent failed transactions and lost funds.
</Warning>

## Path Parameters

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `clientId` | string | The recipient's Fyatu client ID |

## Response

| Field         | Type    | Description                         |
| ------------- | ------- | ----------------------------------- |
| `clientId`    | string  | Verified client ID                  |
| `name`        | string  | Account holder's name               |
| `accountType` | string  | Account type (PERSONAL, BUSINESS)   |
| `status`      | string  | Account status                      |
| `kycVerified` | boolean | Whether account is KYC verified     |
| `canReceive`  | boolean | Whether account can receive payouts |

## Example Usage

<CodeGroup>
  ```php PHP theme={null}
  <?php
  $clientId = 'clt_a1b2c3d4e5f6';

  $response = file_get_contents(
      "https://api.fyatu.com/api/v3/accounts/{$clientId}",
      false,
      stream_context_create([
          'http' => [
              'method' => 'GET',
              'header' => 'Authorization: Bearer ' . $accessToken
          ]
      ])
  );

  $result = json_decode($response, true);

  if ($result['success']) {
      $account = $result['data'];

      if (!$account['canReceive']) {
          echo "Account cannot receive payouts: Status is {$account['status']}\n";
          exit;
      }

      // Show confirmation to user
      echo "Recipient: {$account['name']}\n";
      echo "Account Type: {$account['accountType']}\n";
      echo "KYC Verified: " . ($account['kycVerified'] ? 'Yes' : 'No') . "\n";

      // Proceed with payout...
  } else {
      echo "Account not found\n";
  }
  ```

  ```javascript Node.js theme={null}
  const clientId = 'clt_a1b2c3d4e5f6';

  const response = await fetch(
    `https://api.fyatu.com/api/v3/accounts/${clientId}`,
    {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  );

  const result = await response.json();

  if (result.success) {
    const account = result.data;

    if (!account.canReceive) {
      console.log(`Account cannot receive payouts: Status is ${account.status}`);
      return;
    }

    // Show confirmation to user
    console.log(`Recipient: ${account.name}`);
    console.log(`Account Type: ${account.accountType}`);
    console.log(`KYC Verified: ${account.kycVerified ? 'Yes' : 'No'}`);

    // Proceed with payout...
  } else {
    console.log('Account not found');
  }
  ```
</CodeGroup>

## Example Response

```json theme={null}
{
  "success": true,
  "status": 200,
  "message": "Account verified successfully",
  "data": {
    "clientId": "clt_a1b2c3d4e5f6",
    "name": "Alice Example",
    "accountType": "PERSONAL",
    "status": "ACTIVE",
    "kycVerified": true,
    "canReceive": true
  },
  "meta": {
    "requestId": "req_verify123",
    "timestamp": "2026-01-08T10:00:00+00:00"
  }
}
```

## Status Values

| Status      | canReceive | Description                       |
| ----------- | ---------- | --------------------------------- |
| `ACTIVE`    | `true`     | Account is active and can receive |
| `INACTIVE`  | `false`    | Account is inactive               |
| `SUSPENDED` | `false`    | Account is suspended              |
| `DELETED`   | `false`    | Account is deleted                |

## Best Practices

1. **Always Verify First**: Verify the account before showing payout confirmation to user
2. **Display Name**: Show the recipient's name for user confirmation
3. **Check canReceive**: Only proceed if `canReceive` is `true`
4. **Handle Not Found**: Account may have been deleted or never existed

<Tip>
  For better UX, verify the account as the user types and show the recipient's name before they confirm the payout.
</Tip>

## Error Responses

| Error Code           | HTTP | Description              |
| -------------------- | ---- | ------------------------ |
| `RESOURCE_NOT_FOUND` | 404  | Account not found        |
| `AUTH_TOKEN_INVALID` | 401  | Invalid or expired token |


## OpenAPI

````yaml v3/openapi.json GET /accounts/{clientId}
openapi: 3.1.0
info:
  title: FYATU API v3
  description: >-
    FYATU API v3 with JWT authentication for Collections, Payouts, and Card
    Issuing.
  version: 3.0.0
  contact:
    name: FYATU Support
    url: https://fyatu.com
    email: support@fyatu.com
servers:
  - url: https://api.fyatu.com/api/v3
    description: Production
security: []
tags:
  - name: Authentication
    description: JWT token management endpoints
  - name: Account
    description: Business account, wallet, and address management
  - name: Collections
    description: Accept payments from customers via checkout sessions
  - name: Refunds
    description: Issue refunds for completed collections
  - name: Payouts
    description: Send money to Fyatu account holders
  - name: Cardholders
    description: Cardholder management for card issuing programs
  - name: Cards
    description: Issue, fund, freeze, and manage virtual cards
  - name: Webhooks
    description: Webhook configuration and management
paths:
  /accounts/{clientId}:
    get:
      tags:
        - Payouts
      summary: Verify Account
      description: >-
        Verify a Fyatu account exists and is active before sending a payout.
        Returns account holder name for confirmation.
      operationId: verifyAccount
      parameters:
        - name: clientId
          in: path
          required: true
          schema:
            type: string
            example: clt_a1b2c3d4e5f6
          description: Recipient's Fyatu client ID
      responses:
        '200':
          description: Account verified successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountVerifyResponse'
              example:
                success: true
                status: 200
                message: Account verified successfully
                data:
                  clientId: clt_a1b2c3d4e5f6
                  name: Alice Example
                  accountType: PERSONAL
                  isActive: true
                  status: ACTIVE
                  kycVerified: true
                  canReceive: true
                meta:
                  requestId: req_abc123
                  timestamp: '2026-01-08T10:30:00+00:00'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                status: 404
                message: Account not found or inactive
                error:
                  code: RESOURCE_NOT_FOUND
                meta:
                  requestId: req_abc123
                  timestamp: '2026-01-08T10:30:00+00:00'
      security:
        - BearerAuth: []
components:
  schemas:
    AccountVerifyResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        status:
          type: integer
          example: 200
        message:
          type: string
        data:
          $ref: '#/components/schemas/AccountVerifyData'
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        status:
          type: integer
          example: 401
        message:
          type: string
          example: Invalid credentials
        error:
          $ref: '#/components/schemas/Error'
        meta:
          $ref: '#/components/schemas/Meta'
    AccountVerifyData:
      type: object
      properties:
        clientId:
          type: string
        name:
          type: string
        accountType:
          type: string
          enum:
            - PERSONAL
            - BUSINESS
          description: Type of account
        isActive:
          type: boolean
        status:
          type: string
          description: Account status
        kycVerified:
          type: boolean
          description: Whether KYC verification is complete
        canReceive:
          type: boolean
    Meta:
      type: object
      properties:
        requestId:
          type: string
          description: Unique request ID for tracking
          example: req_abc123def456
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the response
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code for programmatic handling
          example: AUTH_INVALID_CREDENTIALS
        details:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
          description: Validation error details (for VALIDATION_ERROR)
    ValidationError:
      type: object
      properties:
        field:
          type: string
          description: Field that failed validation
          example: appId
        message:
          type: string
          description: Validation error message
          example: AppId is required
  responses:
    Unauthorized:
      description: Authentication required or token invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            status: 401
            message: Unable to identify business
            error:
              code: AUTH_TOKEN_INVALID
            meta:
              requestId: req_abc123
              timestamp: '2026-01-05T10:30:00+00:00'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token obtained from /auth/token

````