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

# Verify Account

> Verify whether an OLIVE account ID exists

<Info>
  Use this endpoint to confirm that an `account_id` exists before routing funds or creating a payment flow around that account.
</Info>

## Request

<ParamField header="X-API-Key-ID" type="string" required>
  API key ID assigned to the integration
</ParamField>

<ParamField header="X-Timestamp" type="string" required>
  RFC3339 timestamp used in the HMAC signature
</ParamField>

<ParamField header="X-Signature" type="string" required>
  Hex-encoded HMAC-SHA256 of the request
</ParamField>

### Body Parameters

<ParamField body="account_id" type="string" required>
  OLIVE account ID to verify
</ParamField>

***

## Response

<ResponseField name="success" type="boolean">
  Whether the verification request completed successfully
</ResponseField>

<ResponseField name="exists" type="boolean">
  Whether the account exists
</ResponseField>

<ResponseField name="message" type="string">
  Verification result message
</ResponseField>

<ResponseField name="account_id" type="string">
  Echo of the requested account ID
</ResponseField>

***

## Example

<RequestExample>
  ```bash cURL theme={null}
  BODY='{"account_id":"acc_12345678"}'
  TIMESTAMP='2026-03-10T12:00:00Z'
  SIGNATURE=$(printf 'POST\n/api/v1/payment/verify-account\n%s\n%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$OLIVE_HMAC_SECRET" -hex | sed 's/^.* //')

  curl -X POST "https://demo.api.vultlocal.com/api/v1/payment/verify-account" \
    -H "X-API-Key-ID: $OLIVE_API_KEY_ID" \
    -H "X-Timestamp: $TIMESTAMP" \
    -H "X-Signature: $SIGNATURE" \
    -H "Content-Type: application/json" \
    -d "$BODY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Exists theme={null}
  {
    "success": true,
    "exists": true,
    "message": "Account verified",
    "account_id": "acc_12345678"
  }
  ```

  ```json 400 Invalid theme={null}
  {
    "success": false,
    "error": "Account not found"
  }
  ```
</ResponseExample>

***

## Errors

| Status | Code                         | Description                                                     |
| ------ | ---------------------------- | --------------------------------------------------------------- |
| 400    | Validation or business error | Invalid payload or account not found                            |
| 401    | HMAC auth error              | Missing/invalid `X-API-Key-ID`, `X-Timestamp`, or `X-Signature` |
| 500    | Internal error               | Server error                                                    |


## OpenAPI

````yaml olive-openapi.json POST /payment/verify-account
openapi: 3.0.0
info:
  description: >-
    API Gateway for OLIVE NFC Card Payment System - Comprehensive payment, card
    management, agent operations, and admin authentication. All /api/v1 routes
    require authentication using either API Key or JWT token.
  title: OLIVE NFC Card Payment API
  termsOfService: http://swagger.io/terms/
  contact:
    name: API Support
    email: support@olive.sl
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
  - url: https://olive-gateway-a6ba.onrender.com/api/v1
security: []
paths:
  /payment/verify-account:
    post:
      tags:
        - POS
      summary: Verify if account ID exists
      description: >-
        Verify if an OLIVE account ID exists in the database (HMAC authenticated
        endpoint for processors)
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handler.VerifyAccountExistsRequest'
        description: Account verification details
        required: true
      responses:
        '200':
          description: Account verification result
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
components:
  schemas:
    handler.VerifyAccountExistsRequest:
      type: object
      required:
        - account_id
      properties:
        account_id:
          type: string
          example: acc_12345678

````