PayZu GatewayClientes e cartões

Consultar clientes


Nesta páginaConsulte um clienteListe os clientesErros desta operação

Leia um cliente pelo id ou percorra os clientes da conta, do mais novo para o mais antigo.

Consulte um cliente

bash
curl https://api.sandbox.payzu.dev/v1/customers/cus_bdQT0ls1QMIXVuhngvhbwC \
  -H "Authorization: Bearer SUA_CHAVE_DE_API"

Referência: Consultar um cliente

O address fica null quando o cliente não tem endereço. O metadata fica null quando nunca foi enviado.

Liste os clientes

bash
curl "https://api.sandbox.payzu.dev/v1/customers?search=maria&limit=20" \
  -H "Authorization: Bearer SUA_CHAVE_DE_API"
Resposta
{
  "items": [
    {
      "id": "cus_bdQT0ls1QMIXVuhngvhbwC",
      "name": "Maria Souza",
      "email": "maria@exemplo.com.br",
      "phone": "11912345678",
      "birthdate": "1990-05-20",
      "document": "52998224725",
      "document_type": "cpf",
      "created_at": "2026-11-11T15:20:59.318Z",
      "updated_at": "2026-11-11T15:20:59.325Z",
      "address": {
        "street": "Avenida Paulista",
        "number": "1000",
        "complement": "Sala 14",
        "district": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "zip_code": "01310100",
        "country": "BR"
      },
      "metadata": {
        "internal_id": "1234"
      }
    }
  ],
  "next_cursor": null
}

Referência: Listar os clientes

Cada item de items traz o cliente completo, como na consulta pelo id. Os clientes excluídos não entram na lista.

ParâmetroO que faz
searchProcura no nome, no e-mail, no documento e no telefone.
subscription_statusTraz os clientes com assinatura active, canceled ou incomplete.
plan_idTraz os clientes com assinatura nesse plano.
created_from, created_toTraz os clientes criados nesses dias, em AAAA-MM-DD, no fuso de São Paulo.
cursorAbre a página seguinte, com o next_cursor da anterior.
limitClientes por página, de 1 a 100.

Com subscription_status e plan_id juntos, os dois valem para a mesma assinatura. Parâmetro que a lista não tem é ignorado. A lista não traz total, como explica Paginação.

Erros desta operação

CódigoHTTPMensagem
-404Cliente não encontrado para o id informado.

O 404 vale para cliente excluído, de outra conta ou com id desconhecido. Os erros de autenticação e de validação estão no Catálogo de erros.