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

# Create Verification

> This lets you create a payee verification.

<Warning>
  Tazamatch is coming soon. The APIs listed here are for reference only and are not yet available in production or sandbox.
</Warning>

```bash cURL theme={null}
curl --request POST \
  --url https://service-sandbox.tazapay.com/v3/verify/payee \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "John Doe",
    "type": "individual",
    "beneficiary_details": {
      "destination_details": {
        "type": "bank",
        "bank": {
          "account_number": "9876543210",
          "bank_codes": {
            "ifsc_code": "HDFC0001234"
          },
          "country": "IN",
          "currency": "INR"
        }
      }
    },
    "reference_id": "your-internal-ref-001"
  }'
```

<Tabs>
  <Tab title="valid — strong match">
    ```json 200 theme={null}
    {
      "status": "success",
      "message": "",
      "data": {
        "id": "pyv_xxxx",
        "object": "verification",
        "verification_status": "valid",
        "status_description": "ValidationSucceeded",
        "beneficiary": "",
        "beneficiary_details": {
          "type": "individual",
          "email": "",
          "tax_id": "",
          "phone": {
            "calling_code": "",
            "number": ""
          },
          "address": {
            "line1": "",
            "line2": "",
            "city": "",
            "state": "",
            "postal_code": "",
            "country": ""
          },
          "destination_details": {
            "type": "bank",
            "bank": {
              "account_holder_name": "John Doe",
              "account_holder_name_local": "",
              "account_number": "9876543210",
              "account_type": "",
              "address": null,
              "bank_codes": {
                "ifsc_code": "HDFC0001234"
              },
              "bank_name": "",
              "branch_name": "",
              "country": "IN",
              "currency": "INR",
              "firc_required": false,
              "iban": "",
              "phone": null,
              "purpose_code": ""
            }
          }
        },
        "verified_information": {
          "account_exists": true,
          "additional_information": null,
          "beneficiary_type": "individual",
          "name_match_details": {
            "type": "continuous",
            "value": 1,
            "summary": "strong_match",
            "corrected_name_returned": "",
            "matched_name_translation": ""
          },
          "transaction_activity_details": null
        },
        "balance": {
          "holding_currency": "USD",
          "initial_balance": 99845,
          "balance_impact": -25,
          "balance_remaining": 99820,
          "balance_transaction_id": "btr_xxxx"
        },
        "metadata": null,
        "reference_id": "your-internal-ref-001",
        "created_at": "2026-04-07T10:00:00Z",
        "updated_at": "2026-04-07T10:00:00Z"
      }
    }
    ```
  </Tab>

  <Tab title="valid — partial match">
    ```json 200 theme={null}
    {
      "status": "success",
      "message": "",
      "data": {
        "id": "pyv_xxxx",
        "object": "verification",
        "verification_status": "valid",
        "status_description": "ValidationSucceeded",
        "beneficiary": "",
        "beneficiary_details": {
          "type": "individual",
          "email": "",
          "tax_id": "",
          "phone": {
            "calling_code": "",
            "number": ""
          },
          "address": {
            "line1": "",
            "line2": "",
            "city": "",
            "state": "",
            "postal_code": "",
            "country": ""
          },
          "destination_details": {
            "type": "bank",
            "bank": {
              "account_holder_name": "Jonathan Doe",
              "account_holder_name_local": "",
              "account_number": "9876543210",
              "account_type": "",
              "address": null,
              "bank_codes": {
                "ifsc_code": "HDFC0001234"
              },
              "bank_name": "",
              "branch_name": "",
              "country": "IN",
              "currency": "INR",
              "firc_required": false,
              "iban": "",
              "phone": null,
              "purpose_code": ""
            }
          }
        },
        "verified_information": {
          "account_exists": true,
          "additional_information": null,
          "beneficiary_type": "individual",
          "name_match_details": {
            "type": "continuous",
            "value": 0.6,
            "summary": "partial_match",
            "corrected_name_returned": "Jonathan Doe",
            "matched_name_translation": ""
          },
          "transaction_activity_details": null
        },
        "balance": {
          "holding_currency": "USD",
          "initial_balance": 99845,
          "balance_impact": -25,
          "balance_remaining": 99820,
          "balance_transaction_id": "btr_xxxx"
        },
        "metadata": null,
        "reference_id": "your-internal-ref-001",
        "created_at": "2026-04-07T10:00:00Z",
        "updated_at": "2026-04-07T10:00:00Z"
      }
    }
    ```
  </Tab>

  <Tab title="valid — no match score">
    ```json 200 theme={null}
    {
      "status": "success",
      "message": "",
      "data": {
        "id": "pyv_xxxx",
        "object": "verification",
        "verification_status": "valid",
        "status_description": "ValidationSucceeded",
        "beneficiary": "",
        "beneficiary_details": {
          "type": "individual",
          "email": "",
          "tax_id": "",
          "phone": {
            "calling_code": "",
            "number": ""
          },
          "address": {
            "line1": "",
            "line2": "",
            "city": "",
            "state": "",
            "postal_code": "",
            "country": ""
          },
          "destination_details": {
            "type": "bank",
            "bank": {
              "account_holder_name": "",
              "account_holder_name_local": "",
              "account_number": "9876543210",
              "account_type": "",
              "address": null,
              "bank_codes": {
                "ifsc_code": "HDFC0001234"
              },
              "bank_name": "",
              "branch_name": "",
              "country": "IN",
              "currency": "INR",
              "firc_required": false,
              "iban": "",
              "phone": null,
              "purpose_code": ""
            }
          }
        },
        "verified_information": {
          "account_exists": true,
          "additional_information": null,
          "beneficiary_type": "individual",
          "name_match_details": null,
          "transaction_activity_details": null
        },
        "balance": {
          "holding_currency": "USD",
          "initial_balance": 99845,
          "balance_impact": -25,
          "balance_remaining": 99820,
          "balance_transaction_id": "btr_xxxx"
        },
        "metadata": null,
        "reference_id": "your-internal-ref-001",
        "created_at": "2026-04-07T10:00:00Z",
        "updated_at": "2026-04-07T10:00:00Z"
      }
    }
    ```
  </Tab>

  <Tab title="invalid">
    ```json 200 theme={null}
    {
      "status": "success",
      "message": "",
      "data": {
        "id": "pyv_xxxx",
        "object": "verification",
        "verification_status": "invalid",
        "status_description": "ValidationFailed",
        "beneficiary": "",
        "beneficiary_details": {
          "type": "individual",
          "email": "",
          "tax_id": "",
          "phone": {
            "calling_code": "",
            "number": ""
          },
          "address": {
            "line1": "",
            "line2": "",
            "city": "",
            "state": "",
            "postal_code": "",
            "country": ""
          },
          "destination_details": {
            "type": "bank",
            "bank": {
              "account_holder_name": "",
              "account_holder_name_local": "",
              "account_number": "9876543210",
              "account_type": "",
              "address": null,
              "bank_codes": {
                "ifsc_code": "HDFC0001234"
              },
              "bank_name": "",
              "branch_name": "",
              "country": "IN",
              "currency": "INR",
              "firc_required": false,
              "iban": "",
              "phone": null,
              "purpose_code": ""
            }
          }
        },
        "verified_information": {
          "account_exists": false,
          "additional_information": null,
          "beneficiary_type": "",
          "name_match_details": null,
          "transaction_activity_details": null
        },
        "balance": {
          "holding_currency": "USD",
          "initial_balance": 99845,
          "balance_impact": -25,
          "balance_remaining": 99820,
          "balance_transaction_id": "btr_xxxx"
        },
        "metadata": null,
        "reference_id": "your-internal-ref-001",
        "created_at": "2026-04-07T10:00:00Z",
        "updated_at": "2026-04-07T10:00:00Z"
      }
    }
    ```
  </Tab>

  <Tab title="not_supported">
    ```json 200 theme={null}
    {
      "status": "success",
      "message": "",
      "data": {
        "id": "pyv_xxxx",
        "object": "verification",
        "verification_status": "not_supported",
        "status_description": "VerificationNotSupported",
        "beneficiary": "",
        "beneficiary_details": {
          "type": "individual",
          "email": "",
          "tax_id": "",
          "phone": {
            "calling_code": "",
            "number": ""
          },
          "address": {
            "line1": "",
            "line2": "",
            "city": "",
            "state": "",
            "postal_code": "",
            "country": ""
          },
          "destination_details": {
            "type": "bank",
            "bank": {
              "account_holder_name": "",
              "account_holder_name_local": "",
              "account_number": "9876543210",
              "account_type": "",
              "address": null,
              "bank_codes": {
                "ifsc_code": "HDFC0001234"
              },
              "bank_name": "",
              "branch_name": "",
              "country": "IN",
              "currency": "INR",
              "firc_required": false,
              "iban": "",
              "phone": null,
              "purpose_code": ""
            }
          }
        },
        "verified_information": null,
        "balance": null,
        "metadata": null,
        "reference_id": "your-internal-ref-001",
        "created_at": "2026-04-07T10:00:00Z",
        "updated_at": "2026-04-07T10:00:00Z"
      }
    }
    ```
  </Tab>
</Tabs>

# Initiate Verification

POST `/v3/verify/payee`

Pass exactly one of `beneficiary` (Mode A — saved beneficiary) or `beneficiary_details` (Mode B — inline). Use [Get Verification Metadata](/API-Reference/payee-verification/get-verification-metadata) to determine which fields and bank codes are required for a given corridor.

#### Authorizations

<ParamField header="Authorization" type="string" required>
  Basic authentication header of the form `Basic <encoded-value>`, where `<encoded-value>` is the base64-encoded string `username:password`.
</ParamField>

#### Body

<ParamField body="name" type="string" required>
  Full name of the beneficiary (payee) to match against the account holder.
</ParamField>

<ParamField body="type" type="enum" required>
  Type of beneficiary entity. Allowed: `individual`, `business`.
</ParamField>

<ParamField body="beneficiary" type="string">
  ID of an existing saved beneficiary (`bnf_xxxx`). If provided, inline beneficiary fields (`name`, `destination_details`, etc.) are not required. Pass this **or** `beneficiary_details`, not both.
</ParamField>

<ParamField body="beneficiary_details" type="object">
  Inline payee details. Pass this **or** `beneficiary`, not both.

  <Expandable title="beneficiary_details">
    <ParamField body="email" type="string">
      Email address of the beneficiary.
    </ParamField>

    <ParamField body="destination_details" type="object" required>
      Container object holding payout destination details.

      <Expandable title="destination_details">
        <ParamField body="type" type="enum" required>
          Type of payout destination. Allowed: `bank`, `wallet`, `local_payment_network`.
        </ParamField>

        <ParamField body="bank" type="object">
          Required when `destination_details.type = bank`.

          <Expandable title="bank">
            <ParamField body="account_number" type="string" required>
              Bank account number of the beneficiary.
            </ParamField>

            <ParamField body="iban" type="string">
              IBAN of the beneficiary. Required for IBAN corridors.
            </ParamField>

            <ParamField body="bank_name" type="string">
              Name of the beneficiary's bank.
            </ParamField>

            <ParamField body="branch_name" type="string">
              Name or identifier of the bank branch.
            </ParamField>

            <ParamField body="country" type="string" required>
              Country where the bank account is held (ISO 3166-1 alpha-2).
            </ParamField>

            <ParamField body="currency" type="string" required>
              Currency of the bank account (ISO 4217).
            </ParamField>

            <ParamField body="bank_codes" type="object">
              Container for bank routing identifiers. Which codes are required depends on the corridor — use [Get Verification Metadata](/API-Reference/payee-verification/get-verification-metadata) to check.
            </ParamField>

            <ParamField body="account_type" type="string">
              Type of bank account (e.g. `savings`, `current`, `checking`).
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="local_payment_network" type="object">
          Required when `destination_details.type = local_payment_network`.

          <Expandable title="local_payment_network">
            <ParamField body="type" type="string">
              Type of local payment network (e.g. `upi_inr`, `pix_brl`, `promptpay_thb`).
            </ParamField>

            <ParamField body="deposit_key" type="string">
              Deposit key for the network (e.g. UPI handle, PIX key).
            </ParamField>

            <ParamField body="deposit_key_type" type="string">
              Type of deposit key. Conditionally required depending on network type.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="tax_id" type="string">
      Tax identification number of the beneficiary.
    </ParamField>

    <ParamField body="name_local" type="string">
      Name of the beneficiary in local language or script.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="metadata" type="object">
  Additional key-value data. Max 10 keys; string values ≤ 500 chars each.
</ParamField>

<ParamField body="reference_id" type="string">
  Reference ID of the verification on your system. Echoed in the response.
</ParamField>

#### Response

<ResponseField name="id" type="string">
  Unique identifier for the verification object. Prefix: `pyv_`.
</ResponseField>

<ResponseField name="object" type="string">
  Fixed value: `verification`.
</ResponseField>

<ResponseField name="verification_status" type="enum">
  Current status of the verification. Allowed: `valid`, `invalid`, `pending`, `not_supported`.
</ResponseField>

<ResponseField name="status_description" type="string">
  Human-readable description of the verification status.
</ResponseField>

<ResponseField name="beneficiary" type="string">
  ID of the saved beneficiary used (`bnf_xxxx`). Empty string for inline (Mode B) verifications.
</ResponseField>

<ResponseField name="beneficiary_details" type="object">
  Echo of the beneficiary details submitted in the request or retrieved from the saved beneficiary object.

  <Expandable title="beneficiary_details">
    <ResponseField name="type" type="string">
      Type of beneficiary entity (`individual` or `business`).
    </ResponseField>

    <ResponseField name="email" type="string">
      Email address of the beneficiary.
    </ResponseField>

    <ResponseField name="tax_id" type="string">
      Tax identification number of the beneficiary.
    </ResponseField>

    <ResponseField name="phone" type="object">
      Phone number of the beneficiary.

      <Expandable title="phone">
        <ResponseField name="calling_code" type="string">
          International dialling code (e.g. `+1`, `+91`).
        </ResponseField>

        <ResponseField name="number" type="string">
          Local phone number.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="address" type="object">
      Address of the beneficiary.

      <Expandable title="address">
        <ResponseField name="line1" type="string">
          Address line 1.
        </ResponseField>

        <ResponseField name="line2" type="string">
          Address line 2.
        </ResponseField>

        <ResponseField name="city" type="string">
          City.
        </ResponseField>

        <ResponseField name="state" type="string">
          State or province.
        </ResponseField>

        <ResponseField name="postal_code" type="string">
          Postal or ZIP code.
        </ResponseField>

        <ResponseField name="country" type="string">
          Country (ISO 3166-1 alpha-2).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="destination_details" type="object">
      Destination details echoed from the request.

      <Expandable title="destination_details">
        <ResponseField name="type" type="string">
          Type of payout destination (e.g. `bank`, `local_payment_network`).
        </ResponseField>

        <ResponseField name="bank" type="object">
          Present when `destination_details.type = bank`.

          <Expandable title="bank">
            <ResponseField name="account_holder_name" type="string">
              Name of the account holder as registered at the bank.
            </ResponseField>

            <ResponseField name="account_holder_name_local" type="string">
              Account holder name in local language or script.
            </ResponseField>

            <ResponseField name="account_number" type="string">
              Bank account number.
            </ResponseField>

            <ResponseField name="account_type" type="string">
              Type of bank account (e.g. `savings`, `current`, `checking`).
            </ResponseField>

            <ResponseField name="address" type="object">
              Bank address. `null` if not provided.
            </ResponseField>

            <ResponseField name="bank_codes" type="object">
              Bank routing identifiers (e.g. `ifsc_code`, `swift_code`).
            </ResponseField>

            <ResponseField name="bank_name" type="string">
              Name of the bank.
            </ResponseField>

            <ResponseField name="branch_name" type="string">
              Name or identifier of the bank branch.
            </ResponseField>

            <ResponseField name="country" type="string">
              Country where the bank account is held (ISO 3166-1 alpha-2).
            </ResponseField>

            <ResponseField name="currency" type="string">
              Currency of the bank account (ISO 4217).
            </ResponseField>

            <ResponseField name="firc_required" type="boolean">
              Whether a Foreign Inward Remittance Certificate is required for this corridor.
            </ResponseField>

            <ResponseField name="iban" type="string">
              IBAN of the beneficiary.
            </ResponseField>

            <ResponseField name="phone" type="object">
              Bank phone number. `null` if not provided.
            </ResponseField>

            <ResponseField name="purpose_code" type="string">
              Purpose code for the transfer, where required by the corridor.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="verified_information" type="object">
  Verification result. Present when `verification_status = valid`. `null` for `not_supported`.

  <Expandable title="verified_information">
    <ResponseField name="account_exists" type="boolean">
      Indicates whether the account was found and recognised at the bank.
    </ResponseField>

    <ResponseField name="additional_information" type="object">
      Additional provider-specific information returned for the verification. `null` if not returned.
    </ResponseField>

    <ResponseField name="beneficiary_type" type="string">
      Whether the account belongs to an `individual` or `business`.
    </ResponseField>

    <ResponseField name="name_match_details" type="object">
      Name match result. `null` when the corridor does not support name matching.

      <Expandable title="name_match_details">
        <ResponseField name="type" type="string">
          Scoring methodology used (e.g. `continuous`).
        </ResponseField>

        <ResponseField name="value" type="float">
          Normalised confidence score from `0.0` to `1.0`.
        </ResponseField>

        <ResponseField name="summary" type="enum">
          Tazapay normalised match classification. Allowed: `strong_match`, `partial_match`, `no_match`.
        </ResponseField>

        <ResponseField name="corrected_name_returned" type="string">
          Suggested name returned by the provider where a close but imperfect match was found. Empty string if not returned.
        </ResponseField>

        <ResponseField name="matched_name_translation" type="string">
          Translation of the matched name, where returned by the provider. Empty string if not applicable.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="transaction_activity_details" type="object">
      Transaction activity details returned by the provider (Kinexys only).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="balance" type="object">
  Balance snapshot at the time of this verification. `null` when `verification_status = not_supported` as no charge is applied.

  <Expandable title="balance">
    <ResponseField name="holding_currency" type="string">
      Currency from which the merchant is charged for this verification. Either `USD` or the merchant's primary currency, depending on which is utilised.
    </ResponseField>

    <ResponseField name="initial_balance" type="integer">
      Balance of the holding currency before this deduction.
    </ResponseField>

    <ResponseField name="balance_impact" type="integer">
      Amount consumed for this verification. Expressed as a negative value.
    </ResponseField>

    <ResponseField name="balance_remaining" type="integer">
      Balance of the holding currency remaining after this deduction.
    </ResponseField>

    <ResponseField name="balance_transaction_id" type="string">
      Transaction ID of the balance debit entry. Prefix: `btr_`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object">
  Key-value map of merchant-defined metadata. Echoed from the request if provided. Max 10 keys; string values ≤ 500 chars each.
</ResponseField>

<ResponseField name="reference_id" type="string">
  Your reference ID echoed from the request.
</ResponseField>

<ResponseField name="created_at" type="timestamp">
  Timestamp when the verification object was created.
</ResponseField>

<ResponseField name="updated_at" type="timestamp">
  Timestamp of the last status update.
</ResponseField>