# Payment handle lookup API

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.

Updated 2026-10-30.

## At a glance

- Endpoint: GET https://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

## 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.

## Call it

curl:

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

Python:

```python
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"])
```

JavaScript:

```javascript
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

Python:

```python
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')
```

TypeScript, with the types from https://bewary.app/types/bewary.d.ts:

```typescript
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 }
}
```

## 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 response: unknown

Request: `GET /v1/payment-handle/venmo/venmo`. Captured from the live API on 2026-10-31.

```json
{
  "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
}
```

## Payment handle facts

Every key is in every response, null when unknown. Keys marked coming stay null until their source ships.

| 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 | In | Type | Required | Description |
|---|---|---|---|---|
| `provider` | path | string | yes | cashapp, paypal (PayPal.me) or venmo. |
| `handle` | path | string | yes | 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.

## Reason codes it can return

`LISTED_BLOCKLIST`, `LISTED_CAUTION`, `PLATFORM_TAKEDOWN`, `PLATFORM_WARNING`, `HANDLE_REPORTED`, `HANDLE_INACTIVE`