Customer verification

Customer verification APIs are in preview as part of USD Virtual Accounts.

Verification belongs to the customer, not your merchant transfer profile. A customer must complete Tier 2 verification and have an approved usd_banking capability before you can create their USD virtual account.

Verification path

Customer type	Required order
`INDIVIDUAL`	Submit `TIER_1`, wait for completion, then submit `TIER_2`.
`BUSINESS`	Submit `TIER_2`. Business customers do not submit Tier 1.

Each request creates an immutable verification submission. If a submission is rejected and the customer corrects their information, create a new submission. Previous attempts remain available in the submission history.

Submit individual Tier 1

curl https://api.yara.cash/v1/customers/908a76cf-4ff1-4e0e-bda4-d3a939970abc/verification-submissions \
  --request POST \
  --header "x-yara-api-key: $YARA_API_KEY" \
  --header "X-Idempotency-Key: $(uuidgen)" \
  --header "Content-Type: application/json" \
  --data '{
    "tier": "TIER_1",
    "bvn": "22345678901",
    "image_url": "https://files.example.com/selfie.jpg"
  }'

The endpoint returns 202 Accepted. It does not echo the submitted verification fields.

{
  "data": {
    "id": "a9203946-43ef-45ed-a806-7b0bbd3de424",
    "customer_id": "908a76cf-4ff1-4e0e-bda4-d3a939970abc",
    "tier": "TIER_1",
    "customer_type": "INDIVIDUAL",
    "status": "PENDING",
    "rejection_reasons": [],
    "submitted_at": "2026-08-03T12:05:00Z",
    "created_at": "2026-08-03T12:05:00Z",
    "updated_at": "2026-08-03T12:05:00Z"
  }
}

Submit Tier 2

Tier 2 collects the customer information required for USD banking. The fields depend on the stored customer type:

Individuals submit their address, date of birth, account purpose, expected activity, employment, source of funds, nationality, and identifying document.
Businesses submit their legal information, registered address, expected activity, associated control persons and signers, tax identification, and supporting documents.

Yara derives the verification shape from the customer record. You cannot change the customer type inside a verification request. See the API reference for the complete request schema.

Submission states

State	Meaning
`DRAFT`	Yara stored the submission but has not yet confirmed provider acceptance. Poll the submission; do not submit it again.
`PENDING`	Verification is still being processed.
`VERIFIED`	This tier is complete.
`REJECTED`	Review `rejection_reasons`, correct the information, and create a new submission.
`REQUIRES_REVIEW`	Processing needs additional review or information.

Use these endpoints to inspect the latest state:

GET /v1/customers/{customer_id} for the customer’s normalized status and capabilities.
GET /v1/customers/{customer_id}/verification-submissions for submission history.
GET /v1/customers/{customer_id}/verification-submissions/{submission_id} for one attempt.

The read endpoints never return BVNs, government identification numbers, document contents, image data, or the original verification request.

Verification webhooks

React to submitted, approved, and rejected verification states.

USD Virtual Accounts

Customers and verification

Customers