Look up players

This page shows how to check a player’s game account before the customer pays. It works for top-up products only.

Customers sometimes type the wrong player ID. A player lookup finds the game account for the ID they typed. Then you can ask “Is this you? Sandbox Player” before they pay. This prevents most top-ups to the wrong account.

When lookups work

• A product supports lookups when its catalog row has "player_lookup": true.
• For any other top-up, the lookup returns unsupported.
• Lookups need the same store wallet requirement as live orders (see store wallet). If your store doesn’t meet it, lookups return 403 player_lookup_requirements_not_met.

Send the same recipient you will order with

Look up player profile takes the product_id and the full recipient that you will send to Create order. If fields are missing, you get the same 422 validation_failed details as when you create the order.

Handle all four statuses

Limits and timing

• Cardzone reuses answers for 10 minutes. So repeated lookups of the same player are fast.
• Some games take several seconds to answer. Show a loading spinner, and keep the order button enabled.
• Each store can make 500 lookups per minute, across all its API keys. Above that, you get 429 rate_limited.
• When too many lookups are already waiting for game sites, players without a recent answer get unavailable.

Full example

// cardzone() stands for your own function that calls the Cardzone API with your API key.
async function confirmPlayer(productId, recipient) {
  const response = await cardzone("POST", "/player_profiles", { product_id: productId, recipient });

  if (response.status === 422) return { kind: "fix_fields", details: response.body.error.details };
  if (!response.ok) return { kind: "skip" }; // 403, 429, 5xx: never block checkout

  const { status, profile } = response.body;
  if (status === "found") return { kind: "confirm", name: profile.display_name, avatar: profile.image_url };
  if (status === "not_found") return { kind: "warn" };
  return { kind: "skip" }; // unavailable or unsupported
}

Sandbox lookups check the recipient against the sandbox top-up products. Then they always return found with a fixed Sandbox Player profile.