Payment handle lookup API

Q: How do I check if a Cash App, PayPal or Venmo handle is active?

Call `GET /v1/payment-handle/{provider}/{handle}` with `cashapp`, `paypal` or `venmo`. Handle status is `active`, `inactive` (PayPal only), `not_found`, `refused` or `unknown`, with a separate `verdict`.

The payment handle lookup API at `GET /v1/payment-handle/{provider}/{handle}` reads Cash App, PayPal and Venmo public profile pages. It returns handle status, whether Bewary's scam list names the handle and a `verdict` of `scam`, `suspicious`, `safe` or `unknown`. A service can refuse the read, returning status `refused`. Names, photos and other profile details are never kept or returned. A call costs 1 credit, a free key gets 1,000 credits a month, no card.

Endpoint: GEThttps://api.bewary.app/v1/payment-handle/{provider}/{handle}
Price: 1 credit
Free key: 1,000 credits a month, no card
Returns: verdict, p_scam, entities with typed facts, reason codes
MCP tool: lookup_payment_handle

Try it

Free from this page: 10 lookups a day

GET/v1/payment-handle/{provider}/{handle}

Service Handle

Recorded answer, October 31, 2026

Unknownp_scam0.2000

Entities

payment_handlevenmo/venmoUnknown

Response

{
  "schema_version": "1.7.0",
  "request_id": "req_01M69WJEJW7QQ1DQAA4RM4HZWP",
  "checked_at": "2026-10-31T21:06:41Z",
  "engine": "bewary-engine/3.0.0",
  "models": {
    "calibration": "interim-band-v0"
  },
  "input": {
    "kind": "lookup",
    "channel": "unknown",
    "language": null,
    "region": null
  },
  "verdict": "unknown",
  "p_scam": 0.2,
  "risk_score": 20,
  "confidence": 0,
  "classification": null,
  "reason_codes": [],
  "entities": [
    {
      "id": "e1",
      "type": "payment_handle",
      "value": "venmo/venmo",
      "normalized": "venmo/venmo",
      "role": "payee",
      "verdict": "unknown",
      "p_scam": 0.2,
      "risk_score": 20,
      "reason_codes": [],
      "facts": {
        "provider": "venmo",
        "handle": "venmo",
        "reports": null,
        "status": "active",
        "status_checked_at": "2026-10-31T21:06:41Z"
      },
      "related": [],
      "datasets": [
        {
          "dataset": "payment_profiles",
          "coverage": "WW",
          "in_coverage": true
        },
        {
          "dataset": "community_reports",
          "coverage": "WW",
          "in_coverage": true
        }
      ]
    }
  ],
  "signals": [],
  "degraded": false,
  "degraded_reasons": [],
  "cached": false,
  "explanation": null
}

Call it

curl "https://api.bewary.app/v1/payment-handle/venmo/venmo"

import requests

r = requests.get("https://api.bewary.app/v1/payment-handle/venmo/venmo", timeout=10)
result = r.json()
print(result["verdict"], result["p_scam"], result["reason_codes"])

const res = await fetch("https://api.bewary.app/v1/payment-handle/venmo/venmo")
const result = await res.json()
console.log(result.verdict, result.p_scam, result.reason_codes)

Act on the result

Copy-paste code that turns the answer into a decision. It runs with or without BEWARY_API_KEY. TypeScript uses bewary.d.ts.

import os, requests

def handle_status(provider, handle):
    key = os.environ["BEWARY_API_KEY"]          # a free key: bewary.app/account
    headers = {"Authorization": f"Bearer {key}"}
    r = requests.get(f"https://api.bewary.app/v1/payment-handle/{provider}/{handle.lstrip('$@')}",
                     headers=headers, timeout=10)
    r.raise_for_status()
    result = r.json()
    return result["verdict"], result["entities"][0]["facts"]["status"]

print(handle_status("venmo", "venmo"))
# ('unknown', 'active')

import type { Envelope } from "./bewary"

export async function handleStatus(provider: "cashapp" | "paypal" | "venmo", handle: string) {
  const key = process.env.BEWARY_API_KEY!     // a free key: bewary.app/account
  const headers: Record<string, string> = { Authorization: `Bearer ${key}` }
  const res = await fetch(`https://api.bewary.app/v1/payment-handle/${provider}/${encodeURIComponent(handle.replace(/^[$@]/, ""))}`,
    { headers, signal: AbortSignal.timeout(10_000) })
  if (!res.ok) throw new Error(`Bewary ${res.status}`)
  const r: Envelope = await res.json()
  const e = r.entities[0]
  if (e.type !== "payment_handle") throw new Error("unexpected entity")
  return { verdict: r.verdict, status: e.facts.status }
}

Response

The fields you will use

entities[0].facts.status: active, inactive (PayPal only), not_found, refused (the service refused our read) or unknown.
entities[0].facts.reports: Reports that name the handle.
signals[]: HANDLE_INACTIVE or HANDLE_REPORTED.

Example responses

{  "schema_version": "1.7.0",  "request_id": "req_01M69WJEJW7QQ1DQAA4RM4HZWP",  "checked_at": "2026-10-31T21:06:41Z",  "engine": "bewary-engine/3.0.0",  "models": {    "calibration": "interim-band-v0"  },  "input": {    "kind": "lookup",    "channel": "unknown",    "language": null,    "region": null  },  "verdict": "unknown",  "p_scam": 0.2,  "risk_score": 20,  "confidence": 0,  "classification": null,  "reason_codes": [],  "entities": [    {      "id": "e1",      "type": "payment_handle",      "value": "venmo/venmo",      "normalized": "venmo/venmo",      "role": "payee",      "verdict": "unknown",      "p_scam": 0.2,      "risk_score": 20,      "reason_codes": [],      "facts": {        "provider": "venmo",        "handle": "venmo",        "reports": null,        "status": "active",        "status_checked_at": "2026-10-31T21:06:41Z"      },      "related": [],      "datasets": [        {          "dataset": "payment_profiles",          "coverage": "WW",          "in_coverage": true        },        {          "dataset": "community_reports",          "coverage": "WW",          "in_coverage": true        }      ]    }  ],  "signals": [],  "degraded": false,  "degraded_reasons": [],  "cached": false,  "explanation": null}

Real responses, captured from the live API on 2026-10-31. Every response has this shape: see Response format.

Payment handle facts

Every key is in every response, null when unknown. A key marked Coming stays null until its source ships, so you can code against it now.

Key	Type	Meaning
`provider`	cashapp \| paypal \| venmo or null	The payment service.
`handle`	string or null	The handle, lowercase, without $ or @.
`status`	active \| inactive \| not_found \| refused \| unknown or null	From the service's public profile page. inactive is PayPal only. refused means the service refused our read.
`status_checked_at`	timestamp or null	When the profile page was read.
`reports`	integer or null	Reports that name the handle.

Parameters

Name	Type	Description
`provider`path, required	string	cashapp, paypal (PayPal.me) or venmo.
`handle`path, required	string	The $Cashtag, PayPal.me name or Venmo username, e.g. $examplestore.

Questions

How do I check if a Cash App, PayPal or Venmo handle is active?

Call GET /v1/payment-handle/{provider}/{handle} with cashapp, paypal or venmo. Handle status is active, inactive (PayPal only), not_found, refused or unknown, with a separate verdict.

Does a payment handle lookup return the account holder's name or photo?

No. Bewary reads the public profile page for the handle's status and never keeps or returns the account holder's name, photo or other profile details.

Used for

Marketplaces can check a seller's Cash App handle when a listing requests payment.
A rental platform can warn renters before payment if a landlord's PayPal handle returns `inactive` or `not_found`.
A payout platform can check a submitted Venmo handle before sending a refund or payout.

Reason codes it can return

Code	Meaning	Severity
`LISTED_BLOCKLIST`	On scam blocklist	Critical
`LISTED_CAUTION`	On a broad threat list that also holds spam and malware hosts	Medium
`PLATFORM_TAKEDOWN`	The hosting platform took it down	High
`PLATFORM_WARNING`	The platform shows a phishing or malware warning in front of it	High
`HANDLE_REPORTED`	A payment handle reported in scams	Medium
`HANDLE_INACTIVE`	The payment profile is not active	Medium

Reserved codes are in the contract, not emitted yet. All reason codes

Updated October 30, 2026 · This page as Markdown · Changelog