Lightweight lookup before creating a customer. Answers whether your merchant already has a customer record in the current mode (live vs test). This avoids duplicate wallet generation and prevents 409 errors on POST /customers when you implement idempotent sign-up.
Authentication
Bearer sk_live_* or sk_test_* (or x-api-key header). Dashboard session cookie also works; add X-Mode: test for sandbox data.
How it works
- Provide at least one query parameter: external_id or email.
- If both are provided, external_id is evaluated first; email is only used when external_id is absent or empty after trimming.
- Matching is exact on trimmed strings, scoped to your merchant_id and is_live flag (derived from API key or X-Mode).
- The customer object in the response is a summary (id, external_id, email) — use GET /customers/:id for full addresses.
- Recommended as step 1 in registration: exists → create only when exists is false.
- POST /request-payment also resolves customers by email internally (creates if missing) — use /exists when you manage customers yourself.
HTTP Status Codes
| 200 | Lookup completed (check exists field — both true and false are valid 200 responses) |
| 400 | Missing both external_id and email |
| 401 | Invalid or missing API key / session |
| 403 | Subscription required or IP not allowlisted |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
external_id | string | no | Your application’s user ID for this person (e.g. user_123 from your database) |
email | string | no | Customer email address (case-sensitive match on stored value) |
Response fields
| Name | Type | Required | Description |
|---|---|---|---|
exists | boolean | yes | true if a matching customer was found |
match | string | yes | "external_id" or "email" — which field matched |
customer | object | null | yes | Summary row when exists is true; otherwise null |
customer.id | uuid | no | Gateway customer UUID — store this in your system |
customer.external_id | string | null | no | Your ID if set at creation |
customer.email | string | null | no | Email if set at creation |
Example request
curl -G "https://api.totopay.net/api/v1/customers/exists" \
-H "Authorization: Bearer sk_live_YOUR_KEY" \
--data-urlencode "email=john@example.com"Example response (success)
// Found
{
"exists": true,
"match": "email",
"customer": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"external_id": "user_123",
"email": "john@example.com"
}
}
// Not found
{
"exists": false,
"match": "email",
"customer": null
}Example errors
// 400 — no lookup key
{ "error": "Provide external_id or email" }
// 401
{ "error": "Invalid API key" }
// 403 subscription
{ "error": "Active subscription required", "code": "SUBSCRIPTION_REQUIRED" }